﻿// -------------------------------------------------------------------------
//    @FileName         :    NFShmHashTableWithList.h
//    @Author           :    gaoyi
//    @Date             :    23-2-6
//    @Email			:    445267987@qq.com
//    @Module           :    NFShmHashTableWithList
//
// -------------------------------------------------------------------------

/**
 * @file NFShmHashTableWithList.h
 * @brief 基于共享内存的增强型哈希表实现，融合哈希查找与插入顺序链表功能
 * 
 * @section overview 概述
 * 
 * NFShmHashTableWithList 是一个创新性的共享内存容器，它将高效的哈希表查找功能
 * 与有序链表的插入顺序维护功能完美结合。该实现在API设计上高度兼容STL，同时
 * 针对共享内存环境进行了深度优化，特别适用于需要快速查找和插入顺序维护的应用场景。
 * 
 * @section features 核心特性
 * 
 * 1. **双重数据结构**：
 *    - 哈希表结构：O(1)平均查找、插入、删除性能
 *    - 插入顺序链表：维护元素插入顺序，支持FIFO访问
 *    - 链地址法解决冲突，固定桶数量设计
 *    - 双重迭代器系统：哈希迭代器 + 链表迭代器
 * 
 * 2. **智能LRU功能**：
 *    - 可控的LRU（最近最少使用）访问模式
 *    - enable_lru()/disable_lru() 动态开关控制
 *    - find/count操作可选择性触发LRU更新
 *    - 适用于缓存淘汰策略和热点数据管理
 * 
 * 3. **共享内存优化**：
 *    - 固定大小内存布局，避免动态分配
 *    - 基于索引的双重链表实现，支持进程间共享
 *    - 内存对齐优化，提高访问效率
 *    - 支持CREATE/RESUME模式初始化
 * 
 * 4. **STL高度兼容**：
 *    - 完整的前向迭代器支持（哈希遍历）
 *    - 标准的容器操作（insert、find、erase、clear等）
 *    - 扩展的链表迭代器（按插入顺序遍历）
 *    - 自定义哈希函数和比较函数支持
 * 
 * 5. **扩展功能**：
 *    - 节点池管理和回收
 *    - 容量检查功能（full()、left_size()等）
 *    - 插入顺序迭代器（list_begin()、list_end()等）
 *    - 详细的调试和诊断接口
 *    - 链表完整性验证功能
 * 
 * @section stl_comparison STL容器对比
 * 
 * | 特性 | STL unordered_map | NFShmHashTableWithList |
 * |------|-------------------|------------------------|
 * | **数据结构** | 哈希表(链地址法) | **哈希表+插入顺序链表** |
 * | **容量管理** | 动态扩容，无限制 | 固定容量MAX_SIZE，编译时确定 |
 * | **内存管理** | 堆内存，动态分配 | 共享内存，预分配节点池 |
 * | **桶管理** | 动态调整，自动rehash | 固定桶数量，无rehash |
 * | **插入删除** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 |
 * | **查找访问** | O(1)平均 | O(1)平均，可选LRU更新 |
 * | **迭代器类型** | 前向迭代器（哈希顺序） | **双重迭代器**（哈希+插入顺序） |
 * | **插入顺序** | 不维护 | **自动维护插入顺序** |
 * | **LRU功能** | 不支持 | **内置LRU访问模式** |
 * | **内存布局** | 分散分配 | 连续节点池 |
 * | **进程共享** | 不支持 | **原生支持** |
 * | **异常安全** | 强异常安全保证 | 无异常，错误码返回 |
 * | **内存碎片** | 可能产生 | **无碎片**（固定节点池） |
 * | **负载因子** | 自动维护 | 固定结构，无动态调整 |
 * | **遍历方式** | 只有哈希遍历 | **哈希遍历+插入顺序遍历** |
 * 
 * @section api_compatibility API兼容性
 * 
 * **完全兼容的接口**：
 * - size(), empty(), max_size()
 * - begin(), end() - 哈希遍历迭代器
 * - insert(), insert_unique(), insert_equal()
 * - find(), count(), equal_range()
 * - erase(), clear()
 * - bucket_count(), max_bucket_count()
 * - swap()
 * 
 * **扩展的接口（新增）**：
 * - **链表迭代器**：list_begin(), list_end(), list_cbegin(), list_cend()
 * - **LRU控制**：enable_lru(), disable_lru(), is_lru_enabled()
 * - **容量检查**：full(), left_size()
 * - **共享内存**：CreateInit(), ResumeInit()
 * - **调试接口**：print_structure(), print_detailed(), print_simple(), print_list()
 * - **节点访问**：GetNode(), get_iterator()
 * 
 * **行为差异的接口**：
 * - find(): 当启用LRU时，会将访问的节点移到链表尾部
 * - count(): 当启用LRU时，会触发LRU更新
 * - insert(): 新元素总是添加到链表尾部（保持插入顺序）
 * - erase(): 从哈希表和链表中同时移除
 * - max_size()：返回MAX_SIZE而非理论最大值
 * - bucket_count()：返回固定值MAX_SIZE
 * - 不支持：rehash(), reserve(), load_factor()等动态调整接口
 * 
 * @section usage_examples 使用示例
 * 
 * @subsection basic_usage 基础用法（类似std::unordered_map + 插入顺序）
 * 
 * ```cpp
 * // 定义容量为1000的字符串到整数映射
 * typedef std::pair<std::string, int> KeyValue;
 * struct KeyExtractor { const std::string& operator()(const KeyValue& kv) const { return kv.first; } };
 * 
 * NFShmHashTableWithList<KeyValue, std::string, 1000, 
 *                        std::hash<std::string>, KeyExtractor, 
 *                        std::equal_to<std::string>> table;
 * table.CreateInit();  // 创建模式初始化
 * 
 * // STL兼容的基础操作
 * table.insert_unique(KeyValue("apple", 100));
 * table.insert_unique(KeyValue("banana", 200));
 * table.insert_unique(KeyValue("orange", 300));
 * 
 * // 哈希查找操作（O(1)平均复杂度）
 * auto it = table.find("apple");
 * if (it != table.end()) {
 *     std::cout << "Found: " << it->first << " = " << it->second << std::endl;
 * }
 * 
 * // 按哈希顺序遍历（传统方式）
 * for (auto it = table.begin(); it != table.end(); ++it) {
 *     std::cout << "Hash order: " << it->first << " = " << it->second << std::endl;
 * }
 * 
 * // 按插入顺序遍历（新增功能）
 * for (auto it = table.list_begin(); it != table.list_end(); ++it) {
 *     std::cout << "Insert order: " << it->first << " = " << it->second << std::endl;
 * }
 * 
 * // C++11 范围for循环（按插入顺序）
 * for (const auto& pair : table.list_range()) {
 *     std::cout << pair.first << " = " << pair.second << std::endl;
 * }
 * ```
 * 
 * @subsection lru_usage LRU缓存实现
 * 
 * ```cpp
 * typedef std::pair<int, std::string> CacheItem;
 * struct KeyExtractor { int operator()(const CacheItem& item) const { return item.first; } };
 * 
 * NFShmHashTableWithList<CacheItem, int, 100, 
 *                        std::hash<int>, KeyExtractor, 
 *                        std::equal_to<int>> cache;
 * cache.CreateInit();
 * cache.enable_lru();  // 启用LRU功能
 * 
 * // 插入缓存项（按插入顺序添加到链表尾部）
 * cache.insert_unique(CacheItem(1, "First"));
 * cache.insert_unique(CacheItem(2, "Second"));
 * cache.insert_unique(CacheItem(3, "Third"));
 * 
 * // 访问元素（自动移到链表尾部）
 * auto it = cache.find(1);  // 元素1被访问，移到链表尾部
 * if (it != cache.end()) {
 *     std::cout << "Cache hit: " << it->second << std::endl;
 * }
 * 
 * // LRU淘汰：最少使用的元素在链表头部
 * if (cache.full()) {
 *     auto oldest = cache.list_begin();  // 获取最少使用的元素
 *     std::cout << "Evicting: " << oldest->second << std::endl;
 *     cache.erase(oldest);  // 淘汰最少使用的元素
 * }
 * 
 * // 遍历缓存（从最少使用到最近使用）
 * std::cout << "Cache items (LRU order):" << std::endl;
 * for (auto it = cache.list_begin(); it != cache.list_end(); ++it) {
 *     std::cout << "  " << it->first << ": " << it->second << std::endl;
 * }
 * ```
 * 
 * @subsection ordered_access 有序访问和FIFO队列
 * 
 * ```cpp
 * typedef std::pair<int, std::string> Task;
 * struct TaskKeyExtractor { int operator()(const Task& task) const { return task.first; } };
 * 
 * NFShmHashTableWithList<Task, int, 500, 
 *                        std::hash<int>, TaskKeyExtractor, 
 *                        std::equal_to<int>> taskQueue;
 * taskQueue.CreateInit();
 * taskQueue.disable_lru();  // 禁用LRU，保持严格的插入顺序
 * 
 * // 任务队列：按ID插入任务
 * taskQueue.insert_unique(Task(101, "Process data"));
 * taskQueue.insert_unique(Task(102, "Send email"));
 * taskQueue.insert_unique(Task(103, "Update database"));
 * 
 * // 快速按ID查找任务（O(1)哈希查找）
 * auto taskIt = taskQueue.find(102);
 * if (taskIt != taskQueue.end()) {
 *     std::cout << "Found task: " << taskIt->second << std::endl;
 * }
 * 
 * // FIFO处理：按插入顺序处理任务
 * while (!taskQueue.empty()) {
 *     auto firstTask = taskQueue.list_begin();
 *     std::cout << "Processing task " << firstTask->first 
 *               << ": " << firstTask->second << std::endl;
 *     taskQueue.erase(firstTask);  // 处理完成后移除
 * }
 * ```
 * 
 * @subsection debugging_monitoring 调试和监控
 * 
 * ```cpp
 * NFShmHashTableWithList<KeyValue, std::string, 100, 
 *                        std::hash<std::string>, KeyExtractor, 
 *                        std::equal_to<std::string>> debugTable;
 * 
 * // 容量监控
 * std::cout << "Capacity: " << debugTable.max_size() << std::endl;
 * std::cout << "Current size: " << debugTable.size() << std::endl;
 * std::cout << "Free space: " << debugTable.left_size() << std::endl;
 * std::cout << "Is full: " << (debugTable.full() ? "Yes" : "No") << std::endl;
 * 
 * // 哈希表结构调试
 * debugTable.print_structure();  // 显示桶链表结构
 * debugTable.print_detailed();   // 显示所有节点详细信息
 * debugTable.print_simple();     // 显示简化的桶信息
 * debugTable.print_list();       // 显示插入顺序链表
 * 
 * // 链表完整性验证
 * if (debugTable.ValidateListIntegrity()) {
 *     std::cout << "List integrity: OK" << std::endl;
 * } else {
 *     std::cout << "List integrity: CORRUPTED!" << std::endl;
 * }
 * 
 * // LRU状态监控
 * std::cout << "LRU enabled: " << (debugTable.is_lru_enabled() ? "Yes" : "No") << std::endl;
 * ```
 * 
 * @subsection dual_iteration 双重迭代方式对比
 * 
 * ```cpp
 * NFShmHashTableWithList<KeyValue, std::string, 100, 
 *                        std::hash<std::string>, KeyExtractor, 
 *                        std::equal_to<std::string>> dualTable;
 * 
 * // 插入一些数据
 * dualTable.insert_unique(KeyValue("zebra", 1));
 * dualTable.insert_unique(KeyValue("apple", 2));
 * dualTable.insert_unique(KeyValue("banana", 3));
 * 
 * std::cout << "=== 哈希顺序遍历（性能优化的遍历） ===" << std::endl;
 * for (auto it = dualTable.begin(); it != dualTable.end(); ++it) {
 *     std::cout << it->first << " -> " << it->second << std::endl;
 * }
 * // 输出可能是：apple->2, zebra->1, banana->3 (哈希桶顺序)
 * 
 * std::cout << "\n=== 插入顺序遍历（业务逻辑相关的遍历） ===" << std::endl;
 * for (auto it = dualTable.list_begin(); it != dualTable.list_end(); ++it) {
 *     std::cout << it->first << " -> " << it->second << std::endl;
 * }
 * // 输出：zebra->1, apple->2, banana->3 (严格按插入顺序)
 * 
 * std::cout << "\n=== 统计和性能对比 ===" << std::endl;
 * std::cout << "哈希查找时间复杂度: O(1) 平均" << std::endl;
 * std::cout << "插入顺序遍历复杂度: O(n)" << std::endl;
 * std::cout << "内存额外开销: 每节点2个索引（prev/next）" << std::endl;
 * ```
 * 
 * @section performance_characteristics 性能特征
 * 
 * | 操作 | STL unordered_map | NFShmHashTableWithList |
 * |------|-------------------|------------------------|
 * | **查找 find** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 + 可选LRU更新 |
 * | **插入 insert** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 + O(1)链表更新 |
 * | **删除 erase** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 + O(1)链表更新 |
 * | **哈希遍历** | O(n) | O(n) |
 * | **插入顺序遍历** | 不支持 | **O(n)** |
 * | **LRU访问** | 不支持 | **O(1)** |
 * | **rehash** | O(n) | **不支持**（固定结构） |
 * | **内存分配** | 动态分配 | 预分配固定内存 |
 * | **缓存友好性** | 中等（桶分散） | **较好**（连续节点池） |
 * | **内存开销** | 动态 | 固定MAX_SIZE * sizeof(Node) + 链表指针 |
 * | **负载因子** | 自动维护 | 需要预估合理MAX_SIZE |
 * 
 * @section memory_layout 内存布局
 * 
 * ```
 * NFShmHashTableWithList 内存结构：
 * ┌─────────────────┐
 * │   管理数据       │ <- 基类信息，元素数量，LRU状态等
 * ├─────────────────┤
 * │   链表管理       │ <- m_listHead, m_listTail, m_enableLRU
 * ├─────────────────┤
 * │   桶索引数组     │ <- m_bucketsFirstIdx[MAX_SIZE]
 * │   [0] -> node_x │    ├─ 桶0的首节点索引
 * │   [1] -> node_y │    ├─ 桶1的首节点索引
 * │   ...           │    ├─ ...
 * │   [MAX-1] -> -1 │    └─ 桶MAX_SIZE-1（空桶）
 * ├─────────────────┤
 * │   节点池         │ <- m_mem[MAX_SIZE] (AlignedStorage)
 * │   [0] 节点0      │    ├─ value + hash_next + list_prev + list_next + valid
 * │   [1] 节点1      │    ├─ ...
 * │   ...           │    ├─ ...
 * │   [MAX-1] 节点   │    └─ 最后一个节点
 * └─────────────────┘
 * 
 * 增强节点结构：
 * ┌─────────────────┐
 * │   m_value       │ <- 存储的键值对或值
 * │   m_next        │ <- 哈希链表中下一个节点索引
 * │   m_listPrev    │ <- 插入顺序链表中前一个节点索引
 * │   m_listNext    │ <- 插入顺序链表中下一个节点索引
 * │   m_valid       │ <- 节点是否有效
 * │   m_self        │ <- 自身索引（调试用）
 * └─────────────────┘
 * 
 * 双重链表示例：
 * 哈希桶链表（查找性能）：
 * 桶0: node5 -> node12 -> node89 -> -1
 * 桶1: node3 -> -1
 * 桶2: -1 (空桶)
 * 桶3: node7 -> node24 -> -1
 * 
 * 插入顺序链表（业务逻辑）：
 * head -> node3 -> node5 -> node7 -> node12 -> node24 -> node89 -> tail
 *         (第1个)  (第2个)  (第3个)  (第4个)   (第5个)   (第6个)
 * 
 * LRU访问后的链表变化：
 * 访问node5后: head -> node3 -> node7 -> node12 -> node24 -> node89 -> node5 -> tail
 *                      (node5移到尾部，成为最近访问)
 * 
 * 优势总结：
 * - 哈希查找：O(1)平均复杂度
 * - 插入顺序：严格维护，适合FIFO场景
 * - LRU功能：高效的缓存淘汰策略
 * - 内存效率：固定布局，无碎片
 * - 进程共享：基于索引，地址无关
 * ```
 * 
 * @section thread_safety 线程安全
 * 
 * - **非线程安全**：需要外部同步机制
 * - **共享内存兼容**：多进程可安全访问（需进程间锁）
 * - **无内部锁**：避免性能开销，由用户控制并发
 * - **迭代器稳定性**：插入删除可能影响其他迭代器
 * - **LRU操作**：find操作可能修改链表结构，需要写锁保护
 * 
 * @section migration_guide 从STL迁移指南
 * 
 * 1. **包含头文件**：
 *    ```cpp
 *    // 替换
 *    #include <unordered_map>
 *    // 为
 *    #include "NFComm/NFShmStl/NFShmHashTableWithList.h"
 *    ```
 * 
 * 2. **类型定义**：
 *    ```cpp
 *    // STL
 *    std::unordered_map<std::string, int> map;
 *    
 *    // NFShmHashTableWithList（需要完整模板参数）
 *    typedef std::pair<std::string, int> KeyValue;
 *    struct KeyExtractor { const std::string& operator()(const KeyValue& kv) const { return kv.first; } };
 *    
 *    NFShmHashTableWithList<KeyValue, std::string, 1000,
 *                           std::hash<std::string>, 
 *                           KeyExtractor,
 *                           std::equal_to<std::string>> map;
 *    ```
 * 
 * 3. **初始化**：
 *    ```cpp
 *    // 添加初始化调用
 *    map.CreateInit();  // 或 ResumeInit() 用于共享内存恢复
 *    ```
 * 
 * 4. **插入操作**：
 *    ```cpp
 *    // STL方式
 *    map["key"] = value;
 *    map.insert({key, value});
 *    
 *    // NFShmHashTableWithList方式
 *    map.insert_unique(KeyValue(key, value));
 *    // 或使用find_or_insert
 *    map.find_or_insert(KeyValue(key, value)) = value;
 *    ```
 * 
 * 5. **遍历方式**：
 *    ```cpp
 *    // STL方式（仅哈希顺序）
 *    for (const auto& pair : map) {
 *        // 哈希顺序遍历
 *    }
 *    
 *    // NFShmHashTableWithList方式（双重选择）
 *    // 哈希顺序遍历（兼容STL）
 *    for (auto it = map.begin(); it != map.end(); ++it) {
 *        // 哈希顺序
 *    }
 *    
 *    // 插入顺序遍历（新增功能）
 *    for (auto it = map.list_begin(); it != map.list_end(); ++it) {
 *        // 插入顺序
 *    }
 *    ```
 * 
 * 6. **LRU功能**：
 *    ```cpp
 *    // 启用LRU缓存功能
 *    map.enable_lru();
 *    
 *    // 访问元素（自动LRU更新）
 *    auto it = map.find(key);
 *    
 *    // 获取最少使用的元素
 *    auto lru = map.list_begin();
 *    
 *    // 淘汰最少使用的元素
 *    map.erase(lru);
 *    ```
 * 
 * 7. **容量管理**：
 *    ```cpp
 *    // 添加容量检查
 *    if (map.full()) {
 *        // 处理容量已满的情况
 *    }
 *    
 *    // 移除无限容量假设
 *    while (!map.full()) {
 *        map.insert_unique(getData());  // 安全插入
 *    }
 *    ```
 * 
 * @section best_practices 最佳实践
 * 
 * 1. **场景选择**：
 *    - **缓存系统**：启用LRU，结合哈希查找和淘汰策略
 *    - **任务队列**：禁用LRU，严格维护FIFO顺序
 *    - **调试监控**：利用插入顺序遍历观察数据变化
 *    - **数据分析**：双重遍历方式，适应不同分析需求
 * 
 * 2. **LRU管理**：
 *    - 根据使用场景选择开启或关闭LRU
 *    - LRU开启时，find/count操作有额外开销
 *    - 缓存场景优先考虑LRU，队列场景避免使用
 * 
 * 3. **容量规划**：
 *    - 根据预期数据量和负载因子选择MAX_SIZE
 *    - 考虑哈希分布质量，避免过多冲突
 *    - 预留适当空间，避免频繁的满容量状态
 * 
 * 4. **迭代器使用**：
 *    - 根据业务需求选择哈希迭代器或链表迭代器
 *    - 插入删除可能使迭代器失效，及时更新
 *    - LRU操作会改变链表迭代器顺序
 * 
 * 5. **性能优化**：
 *    - 使用高质量哈希函数，确保均匀分布
 *    - 合理设置容量，避免过高的负载因子
 *    - 批量操作时考虑LRU的性能影响
 *    - 调试时使用print_*系列函数诊断性能问题
 * 
 * 6. **调试技巧**：
 *    - 使用ValidateListIntegrity()验证数据完整性
 *    - print_list()专门调试插入顺序链表
 *    - 监控left_size()预防容量不足
 *    - 对比哈希遍历和链表遍历的结果差异
 * 
 * @warning 注意事项
 * - 固定容量限制，超出MAX_SIZE的操作会失败
 * - LRU功能会在查找时修改数据结构，需要考虑并发安全
 * - 插入顺序链表增加了额外的内存开销（每节点2个额外索引）
 * - 不支持动态rehash，需要合理预估容量和负载因子
 * - 哈希函数质量直接影响性能，避免频繁冲突
 * - 共享内存环境下需要考虑进程崩溃的数据恢复
 * - 非线程安全，多线程访问需要外部同步
 * - LRU操作可能改变链表迭代器的访问顺序
 * 
 * @see NFShmHashTable - 基础共享内存哈希表实现
 * @see NFShmVector - 基于共享内存的动态数组实现
 * @see NFShmList - 基于共享内存的双向链表实现
 * @see std::unordered_map - 标准无序关联容器
 * @see std::unordered_set - 标准无序集合容器
 * 
 * @author gaoyi
 * @date 2023-02-06
 */
// -------------------------------------------------------------------------
//    @FileName         :    NFShmHashTableWithList.h
//    @Author           :    gaoyi
//    @Date             :    23-2-6
//    @Email			:    445267987@qq.com
//    @Module           :    NFShmHashTableWithList
//
// -------------------------------------------------------------------------

/**
 * @file NFShmHashTableWithList.h
 * @brief 基于共享内存的增强型哈希表实现，融合哈希查找与插入顺序链表功能
 *
 * @section overview 概述
 *
 * NFShmHashTableWithList 是一个创新性的共享内存容器，它将高效的哈希表查找功能
 * 与有序链表的插入顺序维护功能完美结合。该实现在API设计上高度兼容STL，同时
 * 针对共享内存环境进行了深度优化，特别适用于需要快速查找和插入顺序维护的应用场景。
 *
 * @section features 核心特性
 *
 * 1. **双重数据结构**：
 *    - 哈希表结构：O(1)平均查找、插入、删除性能
 *    - 插入顺序链表：维护元素插入顺序，支持FIFO访问
 *    - 链地址法解决冲突，固定桶数量设计
 *    - 双重迭代器系统：哈希迭代器 + 链表迭代器
 *
 * 2. **智能LRU功能**：
 *    - 可控的LRU（最近最少使用）访问模式
 *    - enable_lru()/disable_lru() 动态开关控制
 *    - find/count操作可选择性触发LRU更新
 *    - 适用于缓存淘汰策略和热点数据管理
 *
 * 3. **共享内存优化**：
 *    - 固定大小内存布局，避免动态分配
 *    - 基于索引的双重链表实现，支持进程间共享
 *    - 内存对齐优化，提高访问效率
 *    - 支持CREATE/RESUME模式初始化
 *
 * 4. **STL高度兼容**：
 *    - 完整的前向迭代器支持（哈希遍历）
 *    - 标准的容器操作（insert、find、erase、clear等）
 *    - 扩展的链表迭代器（按插入顺序遍历）
 *    - 自定义哈希函数和比较函数支持
 *
 * 5. **扩展功能**：
 *    - 节点池管理和回收
 *    - 容量检查功能（full()、left_size()等）
 *    - 插入顺序迭代器（list_begin()、list_end()等）
 *    - 详细的调试和诊断接口
 *    - 链表完整性验证功能
 *
 * @section stl_comparison STL容器对比
 *
 * | 特性 | STL unordered_map | NFShmHashTableWithList |
 * |------|-------------------|------------------------|
 * | **数据结构** | 哈希表(链地址法) | **哈希表+插入顺序链表** |
 * | **容量管理** | 动态扩容，无限制 | 固定容量MAX_SIZE，编译时确定 |
 * | **内存管理** | 堆内存，动态分配 | 共享内存，预分配节点池 |
 * | **桶管理** | 动态调整，自动rehash | 固定桶数量，无rehash |
 * | **插入删除** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 |
 * | **查找访问** | O(1)平均 | O(1)平均，可选LRU更新 |
 * | **迭代器类型** | 前向迭代器（哈希顺序） | **双重迭代器**（哈希+插入顺序） |
 * | **插入顺序** | 不维护 | **自动维护插入顺序** |
 * | **LRU功能** | 不支持 | **内置LRU访问模式** |
 * | **内存布局** | 分散分配 | 连续节点池 |
 * | **进程共享** | 不支持 | **原生支持** |
 * | **异常安全** | 强异常安全保证 | 无异常，错误码返回 |
 * | **内存碎片** | 可能产生 | **无碎片**（固定节点池） |
 * | **负载因子** | 自动维护 | 固定结构，无动态调整 |
 * | **遍历方式** | 只有哈希遍历 | **哈希遍历+插入顺序遍历** |
 *
 * @section api_compatibility API兼容性
 *
 * **完全兼容的接口**：
 * - size(), empty(), max_size()
 * - begin(), end() - 哈希遍历迭代器
 * - insert(), insert_unique(), insert_equal()
 * - find(), count(), equal_range()
 * - erase(), clear()
 * - bucket_count(), max_bucket_count()
 * - swap()
 *
 * **扩展的接口（新增）**：
 * - **链表迭代器**：list_begin(), list_end(), list_cbegin(), list_cend()
 * - **LRU控制**：enable_lru(), disable_lru(), is_lru_enabled()
 * - **容量检查**：full(), left_size()
 * - **共享内存**：CreateInit(), ResumeInit()
 * - **调试接口**：print_structure(), print_detailed(), print_simple(), print_list()
 * - **节点访问**：GetNode(), get_iterator()
 *
 * **行为差异的接口**：
 * - find(): 当启用LRU时，会将访问的节点移到链表尾部
 * - count(): 当启用LRU时，会触发LRU更新
 * - insert(): 新元素总是添加到链表尾部（保持插入顺序）
 * - erase(): 从哈希表和链表中同时移除
 * - max_size()：返回MAX_SIZE而非理论最大值
 * - bucket_count()：返回固定值MAX_SIZE
 * - 不支持：rehash(), reserve(), load_factor()等动态调整接口
 *
 * @section usage_examples 使用示例
 *
 * @subsection basic_usage 基础用法（类似std::unordered_map + 插入顺序）
 *
 * ```cpp
 * // 定义容量为1000的字符串到整数映射
 * typedef std::pair<std::string, int> KeyValue;
 * struct KeyExtractor { const std::string& operator()(const KeyValue& kv) const { return kv.first; } };
 *
 * NFShmHashTableWithList<KeyValue, std::string, 1000,
 *                        std::hash<std::string>, KeyExtractor,
 *                        std::equal_to<std::string>> table;
 * table.CreateInit();  // 创建模式初始化
 *
 * // STL兼容的基础操作
 * table.insert_unique(KeyValue("apple", 100));
 * table.insert_unique(KeyValue("banana", 200));
 * table.insert_unique(KeyValue("orange", 300));
 *
 * // 哈希查找操作（O(1)平均复杂度）
 * auto it = table.find("apple");
 * if (it != table.end()) {
 *     std::cout << "Found: " << it->first << " = " << it->second << std::endl;
 * }
 *
 * // 按哈希顺序遍历（传统方式）
 * for (auto it = table.begin(); it != table.end(); ++it) {
 *     std::cout << "Hash order: " << it->first << " = " << it->second << std::endl;
 * }
 *
 * // 按插入顺序遍历（新增功能）
 * for (auto it = table.list_begin(); it != table.list_end(); ++it) {
 *     std::cout << "Insert order: " << it->first << " = " << it->second << std::endl;
 * }
 *
 * // C++11 范围for循环（按插入顺序）
 * for (const auto& pair : table.list_range()) {
 *     std::cout << pair.first << " = " << pair.second << std::endl;
 * }
 * ```
 *
 * @subsection lru_usage LRU缓存实现
 *
 * ```cpp
 * typedef std::pair<int, std::string> CacheItem;
 * struct KeyExtractor { int operator()(const CacheItem& item) const { return item.first; } };
 *
 * NFShmHashTableWithList<CacheItem, int, 100,
 *                        std::hash<int>, KeyExtractor,
 *                        std::equal_to<int>> cache;
 * cache.CreateInit();
 * cache.enable_lru();  // 启用LRU功能
 *
 * // 插入缓存项（按插入顺序添加到链表尾部）
 * cache.insert_unique(CacheItem(1, "First"));
 * cache.insert_unique(CacheItem(2, "Second"));
 * cache.insert_unique(CacheItem(3, "Third"));
 *
 * // 访问元素（自动移到链表尾部）
 * auto it = cache.find(1);  // 元素1被访问，移到链表尾部
 * if (it != cache.end()) {
 *     std::cout << "Cache hit: " << it->second << std::endl;
 * }
 *
 * // LRU淘汰：最少使用的元素在链表头部
 * if (cache.full()) {
 *     auto oldest = cache.list_begin();  // 获取最少使用的元素
 *     std::cout << "Evicting: " << oldest->second << std::endl;
 *     cache.erase(oldest);  // 淘汰最少使用的元素
 * }
 *
 * // 遍历缓存（从最少使用到最近使用）
 * std::cout << "Cache items (LRU order):" << std::endl;
 * for (auto it = cache.list_begin(); it != cache.list_end(); ++it) {
 *     std::cout << "  " << it->first << ": " << it->second << std::endl;
 * }
 * ```
 *
 * @subsection ordered_access 有序访问和FIFO队列
 *
 * ```cpp
 * typedef std::pair<int, std::string> Task;
 * struct TaskKeyExtractor { int operator()(const Task& task) const { return task.first; } };
 *
 * NFShmHashTableWithList<Task, int, 500,
 *                        std::hash<int>, TaskKeyExtractor,
 *                        std::equal_to<int>> taskQueue;
 * taskQueue.CreateInit();
 * taskQueue.disable_lru();  // 禁用LRU，保持严格的插入顺序
 *
 * // 任务队列：按ID插入任务
 * taskQueue.insert_unique(Task(101, "Process data"));
 * taskQueue.insert_unique(Task(102, "Send email"));
 * taskQueue.insert_unique(Task(103, "Update database"));
 *
 * // 快速按ID查找任务（O(1)哈希查找）
 * auto taskIt = taskQueue.find(102);
 * if (taskIt != taskQueue.end()) {
 *     std::cout << "Found task: " << taskIt->second << std::endl;
 * }
 *
 * // FIFO处理：按插入顺序处理任务
 * while (!taskQueue.empty()) {
 *     auto firstTask = taskQueue.list_begin();
 *     std::cout << "Processing task " << firstTask->first
 *               << ": " << firstTask->second << std::endl;
 *     taskQueue.erase(firstTask);  // 处理完成后移除
 * }
 * ```
 *
 * @subsection debugging_monitoring 调试和监控
 *
 * ```cpp
 * NFShmHashTableWithList<KeyValue, std::string, 100,
 *                        std::hash<std::string>, KeyExtractor,
 *                        std::equal_to<std::string>> debugTable;
 *
 * // 容量监控
 * std::cout << "Capacity: " << debugTable.max_size() << std::endl;
 * std::cout << "Current size: " << debugTable.size() << std::endl;
 * std::cout << "Free space: " << debugTable.left_size() << std::endl;
 * std::cout << "Is full: " << (debugTable.full() ? "Yes" : "No") << std::endl;
 *
 * // 哈希表结构调试
 * debugTable.print_structure();  // 显示桶链表结构
 * debugTable.print_detailed();   // 显示所有节点详细信息
 * debugTable.print_simple();     // 显示简化的桶信息
 * debugTable.print_list();       // 显示插入顺序链表
 *
 * // 链表完整性验证
 * if (debugTable.ValidateListIntegrity()) {
 *     std::cout << "List integrity: OK" << std::endl;
 * } else {
 *     std::cout << "List integrity: CORRUPTED!" << std::endl;
 * }
 *
 * // LRU状态监控
 * std::cout << "LRU enabled: " << (debugTable.is_lru_enabled() ? "Yes" : "No") << std::endl;
 * ```
 *
 * @subsection dual_iteration 双重迭代方式对比
 *
 * ```cpp
 * NFShmHashTableWithList<KeyValue, std::string, 100,
 *                        std::hash<std::string>, KeyExtractor,
 *                        std::equal_to<std::string>> dualTable;
 *
 * // 插入一些数据
 * dualTable.insert_unique(KeyValue("zebra", 1));
 * dualTable.insert_unique(KeyValue("apple", 2));
 * dualTable.insert_unique(KeyValue("banana", 3));
 *
 * std::cout << "=== 哈希顺序遍历（性能优化的遍历） ===" << std::endl;
 * for (auto it = dualTable.begin(); it != dualTable.end(); ++it) {
 *     std::cout << it->first << " -> " << it->second << std::endl;
 * }
 * // 输出可能是：apple->2, zebra->1, banana->3 (哈希桶顺序)
 *
 * std::cout << "\n=== 插入顺序遍历（业务逻辑相关的遍历） ===" << std::endl;
 * for (auto it = dualTable.list_begin(); it != dualTable.list_end(); ++it) {
 *     std::cout << it->first << " -> " << it->second << std::endl;
 * }
 * // 输出：zebra->1, apple->2, banana->3 (严格按插入顺序)
 *
 * std::cout << "\n=== 统计和性能对比 ===" << std::endl;
 * std::cout << "哈希查找时间复杂度: O(1) 平均" << std::endl;
 * std::cout << "插入顺序遍历复杂度: O(n)" << std::endl;
 * std::cout << "内存额外开销: 每节点2个索引（prev/next）" << std::endl;
 * ```
 *
 * @section performance_characteristics 性能特征
 *
 * | 操作 | STL unordered_map | NFShmHashTableWithList |
 * |------|-------------------|------------------------|
 * | **查找 find** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 + 可选LRU更新 |
 * | **插入 insert** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 + O(1)链表更新 |
 * | **删除 erase** | O(1)平均，O(n)最坏 | O(1)平均，O(n)最坏 + O(1)链表更新 |
 * | **哈希遍历** | O(n) | O(n) |
 * | **插入顺序遍历** | 不支持 | **O(n)** |
 * | **LRU访问** | 不支持 | **O(1)** |
 * | **rehash** | O(n) | **不支持**（固定结构） |
 * | **内存分配** | 动态分配 | 预分配固定内存 |
 * | **缓存友好性** | 中等（桶分散） | **较好**（连续节点池） |
 * | **内存开销** | 动态 | 固定MAX_SIZE * sizeof(Node) + 链表指针 |
 * | **负载因子** | 自动维护 | 需要预估合理MAX_SIZE |
 *
 * @section memory_layout 内存布局
 *
 * ```
 * NFShmHashTableWithList 内存结构：
 * ┌─────────────────┐
 * │   管理数据       │ <- 基类信息，元素数量，LRU状态等
 * ├─────────────────┤
 * │   链表管理       │ <- m_listHead, m_listTail, m_enableLRU
 * ├─────────────────┤
 * │   桶索引数组     │ <- m_bucketsFirstIdx[MAX_SIZE]
 * │   [0] -> node_x │    ├─ 桶0的首节点索引
 * │   [1] -> node_y │    ├─ 桶1的首节点索引
 * │   ...           │    ├─ ...
 * │   [MAX-1] -> -1 │    └─ 桶MAX_SIZE-1（空桶）
 * ├─────────────────┤
 * │   节点池         │ <- m_mem[MAX_SIZE] (AlignedStorage)
 * │   [0] 节点0      │    ├─ value + hash_next + list_prev + list_next + valid
 * │   [1] 节点1      │    ├─ ...
 * │   ...           │    ├─ ...
 * │   [MAX-1] 节点   │    └─ 最后一个节点
 * └─────────────────┘
 *
 * 增强节点结构：
 * ┌─────────────────┐
 * │   m_value       │ <- 存储的键值对或值
 * │   m_next        │ <- 哈希链表中下一个节点索引
 * │   m_listPrev    │ <- 插入顺序链表中前一个节点索引
 * │   m_listNext    │ <- 插入顺序链表中下一个节点索引
 * │   m_valid       │ <- 节点是否有效
 * │   m_self        │ <- 自身索引（调试用）
 * └─────────────────┘
 *
 * 双重链表示例：
 * 哈希桶链表（查找性能）：
 * 桶0: node5 -> node12 -> node89 -> -1
 * 桶1: node3 -> -1
 * 桶2: -1 (空桶)
 * 桶3: node7 -> node24 -> -1
 *
 * 插入顺序链表（业务逻辑）：
 * head -> node3 -> node5 -> node7 -> node12 -> node24 -> node89 -> tail
 *         (第1个)  (第2个)  (第3个)  (第4个)   (第5个)   (第6个)
 *
 * LRU访问后的链表变化：
 * 访问node5后: head -> node3 -> node7 -> node12 -> node24 -> node89 -> node5 -> tail
 *                      (node5移到尾部，成为最近访问)
 *
 * 优势总结：
 * - 哈希查找：O(1)平均复杂度
 * - 插入顺序：严格维护，适合FIFO场景
 * - LRU功能：高效的缓存淘汰策略
 * - 内存效率：固定布局，无碎片
 * - 进程共享：基于索引，地址无关
 * ```
 *
 * @section thread_safety 线程安全
 *
 * - **非线程安全**：需要外部同步机制
 * - **共享内存兼容**：多进程可安全访问（需进程间锁）
 * - **无内部锁**：避免性能开销，由用户控制并发
 * - **迭代器稳定性**：插入删除可能影响其他迭代器
 * - **LRU操作**：find操作可能修改链表结构，需要写锁保护
 *
 * @section migration_guide 从STL迁移指南
 *
 * 1. **包含头文件**：
 *    ```cpp
 *    // 替换
 *    #include <unordered_map>
 *    // 为
 *    #include "NFComm/NFShmStl/NFShmHashTableWithList.h"
 *    ```
 *
 * 2. **类型定义**：
 *    ```cpp
 *    // STL
 *    std::unordered_map<std::string, int> map;
 *
 *    // NFShmHashTableWithList（需要完整模板参数）
 *    typedef std::pair<std::string, int> KeyValue;
 *    struct KeyExtractor { const std::string& operator()(const KeyValue& kv) const { return kv.first; } };
 *
 *    NFShmHashTableWithList<KeyValue, std::string, 1000,
 *                           std::hash<std::string>,
 *                           KeyExtractor,
 *                           std::equal_to<std::string>> map;
 *    ```
 *
 * 3. **初始化**：
 *    ```cpp
 *    // 添加初始化调用
 *    map.CreateInit();  // 或 ResumeInit() 用于共享内存恢复
 *    ```
 *
 * 4. **插入操作**：
 *    ```cpp
 *    // STL方式
 *    map["key"] = value;
 *    map.insert({key, value});
 *
 *    // NFShmHashTableWithList方式
 *    map.insert_unique(KeyValue(key, value));
 *    // 或使用find_or_insert
 *    map.find_or_insert(KeyValue(key, value)) = value;
 *    ```
 *
 * 5. **遍历方式**：
 *    ```cpp
 *    // STL方式（仅哈希顺序）
 *    for (const auto& pair : map) {
 *        // 哈希顺序遍历
 *    }
 *
 *    // NFShmHashTableWithList方式（双重选择）
 *    // 哈希顺序遍历（兼容STL）
 *    for (auto it = map.begin(); it != map.end(); ++it) {
 *        // 哈希顺序
 *    }
 *
 *    // 插入顺序遍历（新增功能）
 *    for (auto it = map.list_begin(); it != map.list_end(); ++it) {
 *        // 插入顺序
 *    }
 *    ```
 *
 * 6. **LRU功能**：
 *    ```cpp
 *    // 启用LRU缓存功能
 *    map.enable_lru();
 *
 *    // 访问元素（自动LRU更新）
 *    auto it = map.find(key);
 *
 *    // 获取最少使用的元素
 *    auto lru = map.list_begin();
 *
 *    // 淘汰最少使用的元素
 *    map.erase(lru);
 *    ```
 *
 * 7. **容量管理**：
 *    ```cpp
 *    // 添加容量检查
 *    if (map.full()) {
 *        // 处理容量已满的情况
 *    }
 *
 *    // 移除无限容量假设
 *    while (!map.full()) {
 *        map.insert_unique(getData());  // 安全插入
 *    }
 *    ```
 *
 * @section best_practices 最佳实践
 *
 * 1. **场景选择**：
 *    - **缓存系统**：启用LRU，结合哈希查找和淘汰策略
 *    - **任务队列**：禁用LRU，严格维护FIFO顺序
 *    - **调试监控**：利用插入顺序遍历观察数据变化
 *    - **数据分析**：双重遍历方式，适应不同分析需求
 *
 * 2. **LRU管理**：
 *    - 根据使用场景选择开启或关闭LRU
 *    - LRU开启时，find/count操作有额外开销
 *    - 缓存场景优先考虑LRU，队列场景避免使用
 *
 * 3. **容量规划**：
 *    - 根据预期数据量和负载因子选择MAX_SIZE
 *    - 考虑哈希分布质量，避免过多冲突
 *    - 预留适当空间，避免频繁的满容量状态
 *
 * 4. **迭代器使用**：
 *    - 根据业务需求选择哈希迭代器或链表迭代器
 *    - 插入删除可能使迭代器失效，及时更新
 *    - LRU操作会改变链表迭代器顺序
 *
 * 5. **性能优化**：
 *    - 使用高质量哈希函数，确保均匀分布
 *    - 合理设置容量，避免过高的负载因子
 *    - 批量操作时考虑LRU的性能影响
 *    - 调试时使用print_*系列函数诊断性能问题
 *
 * 6. **调试技巧**：
 *    - 使用ValidateListIntegrity()验证数据完整性
 *    - print_list()专门调试插入顺序链表
 *    - 监控left_size()预防容量不足
 *    - 对比哈希遍历和链表遍历的结果差异
 *
 * @warning 注意事项
 * - 固定容量限制，超出MAX_SIZE的操作会失败
 * - LRU功能会在查找时修改数据结构，需要考虑并发安全
 * - 插入顺序链表增加了额外的内存开销（每节点2个额外索引）
 * - 不支持动态rehash，需要合理预估容量和负载因子
 * - 哈希函数质量直接影响性能，避免频繁冲突
 * - 共享内存环境下需要考虑进程崩溃的数据恢复
 * - 非线程安全，多线程访问需要外部同步
 * - LRU操作可能改变链表迭代器的访问顺序
 *
 * @see NFShmHashTable - 基础共享内存哈希表实现
 * @see NFShmVector - 基于共享内存的动态数组实现
 * @see NFShmList - 基于共享内存的双向链表实现
 * @see std::unordered_map - 标准无序关联容器
 * @see std::unordered_set - 标准无序集合容器
 *
 * @author gaoyi
 * @date 2023-02-06
 */

#pragma once

#include "NFShmStl.h"
#include <iterator>
#include <algorithm>
#include <functional>
#include <vector>
#include <tuple>
#include <cmath>

/****************************************************************************
 * STL标准Hash实现对比分析
 ****************************************************************************
 *
 * 1. 内存管理策略对比：
 *    - STL unordered_map: 动态内存分配，使用allocator管理堆内存
 *    - NFShmHashTableWithList: 固定大小共享内存，预分配所有节点，支持进程间共享
 *
 * 2. 容量管理对比：
 *    - STL: 动态扩容，load_factor超过阈值时自动rehash，桶数量可变
 *    - NFShmHashTableWithList: 固定容量MAX_SIZE，不支持动态扩容，桶数量固定
 *
 * 3. 冲突解决策略对比：
 *    - 都使用链地址法(Separate Chaining)解决冲突
 *    - STL: 使用std::forward_list或类似结构
 *    - NFShmHashTableWithList: 使用索引链表，节点包含next索引而非指针
 *
 * 4. 迭代器实现对比：
 *    - 都实现forward_iterator，支持单向遍历
 *    - STL: 基于指针或智能指针
 *    - NFShmHashTableWithList: 基于索引，需要验证节点有效性
 *
 * 5. 线程安全对比：
 *    - STL: 非线程安全，需要外部同步
 *    - NFShmHashTableWithList: 非线程安全，但支持进程间共享
 *
 * 6. API兼容性：
 *    - 大部分接口与STL兼容：insert, find, erase, begin, end等
 *    - 特有接口：CreateInit, ResumeInit, print_*等调试接口
 *    - 缺少接口：rehash, reserve, bucket_size等动态管理接口
 *****************************************************************************/

/****************************************************************************
 * 链表功能特性说明
 ****************************************************************************
 *
 * NFShmHashTableWithList 在保持哈希表高效查找性能的同时，额外提供了链表功能：
 *
 * 1. 插入顺序维护：
 *    - 自动维护元素的插入顺序，新元素总是添加到链表尾部
 *    - 支持FIFO（先进先出）访问模式，适用于缓存和队列场景
 *    - 实现原理：每个节点包含 m_listPrev 和 m_listNext 索引
 *
 * 2. LRU功能控制：
 *    - 可开关的LRU（最近最少使用）访问模式
 *    - 当启用LRU时，find() 和 count() 操作会将访问的节点移动到链表尾部
 *    - 提供 enable_lru()、disable_lru()、is_lru_enabled() 控制接口
 *    - 适用于缓存淘汰策略实现
 *
 * 3. 链表迭代器：
 *    - list_iterator：非常量链表迭代器，支持按插入顺序遍历
 *    - const_list_iterator：常量链表迭代器
 *    - 提供 list_begin()、list_end()、list_cbegin()、list_cend() 接口
 *    - 与STL风格保持一致，支持范围for循环
 *
 * 4. 内存效率设计：
 *    - 使用索引而非指针，适合共享内存环境
 *    - 链表指针直接集成在节点中，无额外内存分配
 *    - 所有链表操作均为O(1)复杂度
 *
 * 5. 自动维护一致性：
 *    - 插入操作自动将新节点添加到链表尾部
 *    - 删除操作自动从链表中移除节点
 *    - 清空操作自动重置链表状态
 *    - 错误检查确保链表操作的安全性
 *
 * 6. 使用场景：
 *    - 缓存系统：结合哈希查找和LRU淘汰策略
 *    - 有序访问：需要按插入顺序遍历的场景
 *    - 调试和监控：按插入顺序查看数据状态
 *    - 队列实现：支持FIFO访问模式的队列
 *
 * 示例用法：
 * ```cpp
 * // 创建哈希表
 * NFShmHashTableWithList<KeyValue, int, 100, HashFunc, ExtractKey, EqualKey> hashTable;
 * 
 * // 插入数据（自动维护插入顺序）
 * hashTable.insert_unique(KeyValue(1, "First"));
 * hashTable.insert_unique(KeyValue(2, "Second"));
 * 
 * // 按插入顺序遍历
 * for (auto it = hashTable.list_begin(); it != hashTable.list_end(); ++it) {
 *     // 按插入顺序访问元素
 * }
 * 
 * // 启用LRU功能
 * hashTable.enable_lru();
 * auto it = hashTable.find(1);  // 访问元素1，将其移到链表尾部
 *
 * ========== Comprehensive Sort Performance Comparison ==========
五种排序算法性能对比（微秒）
规模     数据模式     SortListInsert(插入) SortListQuick(快速) SortListMerge(归并) SortListMergeFast(优化) SortListSelect(选择) 最快算法             性能优势
----     --------     -------------   -------------   -------------   ----------------   -------------   --------             --------
10       随机数据     3               2               2               0                  3               SortListMergeFast    inf                 x
10       倒序数据     1               1               2               0                  2               SortListMergeFast    inf                 x
10       已排序数据   1               1               1               0                  2               SortListMergeFast    inf                 x
10       部分排序     1               1               1               0                  2               SortListMergeFast    inf                 x

20       随机数据     2               2               4               0                  3               SortListMergeFast    inf                 x
20       倒序数据     1               1               3               0                  4               SortListMergeFast    inf                 x
20       已排序数据   2               1               3               0                  3               SortListMergeFast    inf                 x
20       部分排序     2               1               3               0                  3               SortListMergeFast    inf                 x

30       随机数据     4               5               6               1                  6               SortListMergeFast    6.00                x
30       倒序数据     2               2               5               0                  6               SortListMergeFast    inf                 x
30       已排序数据   4               2               5               1                  5               SortListMergeFast    5.00                x
30       部分排序     4               3               5               1                  6               SortListMergeFast    6.00                x

40       随机数据     5               18              8               3                  9               SortListMergeFast    6.00                x
40       倒序数据     3               4               7               1                  8               SortListMergeFast    8.00                x
40       已排序数据   6               3               7               1                  8               SortListMergeFast    8.00                x
40       部分排序     6               4               8               1                  8               SortListMergeFast    8.00                x

50       随机数据     6               7               11              3                  12              SortListMergeFast    4.00                x
50       倒序数据     3               5               10              4                  32              SortListInsert       10.67               x
50       已排序数据   18              8               17              4                  21              SortListMergeFast    5.25                x
50       部分排序     16              10              18              4                  22              SortListMergeFast    5.50                x


========== 大数据集性能对比（使用LargeTestHashTableWithList）==========
规模     数据模式     SortListInsert(插入) SortListQuick(快速) SortListMerge(归并) SortListMergeFast(优化) SortListSelect(选择) 最快算法             性能优势
----     --------     -------------   -------------   -------------   ----------------   -------------   --------             --------
100      随机数据     55              73              58              8                  47              SortListMergeFast    9.12                x
100      倒序数据     16              20              30              4                  47              SortListMergeFast    11.75               x
100      已排序数据   43              18              29              4                  45              SortListMergeFast    11.25               x
100      部分排序     41              22              33              7                  48              SortListMergeFast    6.86                x

200      随机数据     71              44              61              17                 126             SortListMergeFast    7.41                x
200      倒序数据     23              33              53              10                 146             SortListMergeFast    14.60               x
200      已排序数据   128             27              53              10                 133             SortListMergeFast    13.30               x
200      部分排序     123             35              58              13                 136             SortListMergeFast    10.46               x

500      随机数据     369             111             162             50                 696             SortListMergeFast    13.92               x
500      倒序数据     45              69              134             28                 757             SortListMergeFast    27.04               x
500      已排序数据   698             72              133             29                 738             SortListMergeFast    25.45               x
500      部分排序     650             100             148             44                 752             SortListMergeFast    17.09               x

1000     随机数据     1423            245             347             113                2700            SortListMergeFast    23.89               x
1000     倒序数据     72              146             270             62                 2926            SortListMergeFast    47.19               x
1000     已排序数据   2943            115             267             65                 2864            SortListMergeFast    45.28               x
1000     部分排序     2655            179             323             89                 2974            SortListMergeFast    33.42               x

所有排序算法终极对比（微秒）
规模   数据模式 SortListInsert SortListQuick SortListMerge SortListMergeFast SortListSelect std::vector  std::list    C数组    std::map     std::sort
----   ------   ------------   -----------   -----------   -------------   ------------   ----------   ----------   ------   ----------   ---------
10     随机数据 4              3             3             0               3              0            0            0        3            0
10     倒序数据 1              1             2             0               2              0            0            0        1            0
10     已排序数据 1              1             1             0               2              0            0            0        1            0
10     部分排序 1              1             1             0               2              0            0            0        1            0

50     随机数据 7              9             11            4               14             1            2            1        11           0
50     倒序数据 3              5             9             2               12             0            1            0        8            0
50     已排序数据 9              4             9             2               11             0            0            0        10           0
50     部分排序 9              5             10            2               12             0            1            0        9            0

100    随机数据 101            82            89            8               113            3            4            2        20           1
100    倒序数据 69             61            79            5               112            1            1            1        17           0
100    已排序数据 86             61            79            4               91             0            1            0        17           0
100    部分排序 123            64            81            6               107            2            17           1        18           0

500    随机数据 426            161           212           49              787            23           29           19       109          20
500    倒序数据 109            128           201           29              866            5            8            4        95           4
500    已排序数据 796            102           182           29              885            3            6            2        79           3
500    部分排序 713            164           209           40              892            12           28           9        99           9

1000   随机数据 1528           287           408           112             3008           74           63           62       325          46
1000   倒序数据 124            221           348           59              3289           12           15           26       199          10
1000   已排序数据 3048           167           326           71              3378           13           15           6        193          6
1000   部分排序 2710           237           390           101             3261           27           36           25       227          24

2000   随机数据 6358           596           841           206             11760          106          140          110      496          103
2000   倒序数据 218            406           686           73              12715          24           49           22       404          21
2000   已排序数据 12029          294           717           55              12741          29           29           14       385          14
2000   部分排序 10485          441           729           139             12485          73           91           54       435          58

5000   随机数据 50445          1712          2381          595             77653          306          423          306      1421         298
5000   倒序数据 428            990           1708          243             79320          95           89           60       963          67
5000   已排序数据 74513          819           1686          181             78398          46           86           45       1022         45
5000   部分排序 72771          1186          2089          398             79941          155          243          155      1085         138

10000  随机数据 326723         3448          5030          1033            311386         512          703          508      3109         667
10000  倒序数据 586            1629          3096          477             269953         116          185          110      1928         98
10000  已排序数据 253410         1349          3673          400             262402         76           377          122      1824         85
10000  部分排序 292536         2142          3757          705             276617         353          467          281      2353         353
==============================================================
搜索插入位置函数性能测试
==============================================================
数据规模: 10 元素
  LineSearch: 23 μs (10000 次调用) - 平均 2.30 ns/次
  BinarySearch: 118 μs (10000 次调用) - 平均 11.80 ns/次
  FastSearch: 6 μs (10000 次调用) - 平均 0.60 ns/次
  AdaptiveSearch: 46 μs (10000 次调用) - 平均 4.60 ns/次
  最快算法: FastSearch (6 μs)
  性能对比 (相对于最快算法):
    LineSearch: 3.83x
    BinarySearch: 19.67x
    FastSearch: 1.00x ?
    AdaptiveSearch: 7.67x
  理论复杂度分析:
    LineSearch: O(n) = O(10) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(10) - 需要先收集索引
    FastSearch: O(n) = O(10) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 使用LineSearch (当前数据规模下最优)
--------------------------------------------------------------
数据规模: 50 元素
  LineSearch: 11 μs (10000 次调用) - 平均 1.10 ns/次
  BinarySearch: 11 μs (10000 次调用) - 平均 1.10 ns/次
  FastSearch: 0 μs (10000 次调用) - 平均 0.00 ns/次
  AdaptiveSearch: 111 μs (10000 次调用) - 平均 11.10 ns/次
  最快算法: FastSearch (0 μs)
  性能对比 (相对于最快算法):
    LineSearch: infx
    BinarySearch: infx
    FastSearch: -nan(ind)x ?
    AdaptiveSearch: infx
  理论复杂度分析:
    LineSearch: O(n) = O(50) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(50) - 需要先收集索引
    FastSearch: O(n) = O(50) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 使用LineSearch (当前数据规模下最优)
--------------------------------------------------------------
数据规模: 100 元素
  LineSearch: 128 μs (10000 次调用) - 平均 12.80 ns/次
  BinarySearch: 254 μs (10000 次调用) - 平均 25.40 ns/次
  FastSearch: 65 μs (10000 次调用) - 平均 6.50 ns/次
  AdaptiveSearch: 305 μs (10000 次调用) - 平均 30.50 ns/次
  最快算法: FastSearch (65 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.97x
    BinarySearch: 3.91x
    FastSearch: 1.00x ?
    AdaptiveSearch: 4.69x
  理论复杂度分析:
    LineSearch: O(n) = O(100) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(100) - 需要先收集索引
    FastSearch: O(n) = O(100) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 使用LineSearch (当前数据规模下最优)
--------------------------------------------------------------
数据规模: 200 元素
  LineSearch: 35 μs (10000 次调用) - 平均 3.50 ns/次
  BinarySearch: 393 μs (10000 次调用) - 平均 39.30 ns/次
  FastSearch: 174 μs (10000 次调用) - 平均 17.40 ns/次
  AdaptiveSearch: 318 μs (10000 次调用) - 平均 31.80 ns/次
  最快算法: LineSearch (35 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.00x ?
    BinarySearch: 11.23x
    FastSearch: 4.97x
    AdaptiveSearch: 9.09x
  理论复杂度分析:
    LineSearch: O(n) = O(200) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(200) - 需要先收集索引
    FastSearch: O(n) = O(200) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 使用LineSearch (当前数据规模下最优)
--------------------------------------------------------------
数据规模: 500 元素
  LineSearch: 3506 μs (10000 次调用) - 平均 350.60 ns/次
  BinarySearch: 11965 μs (10000 次调用) - 平均 1196.50 ns/次
  FastSearch: 2573 μs (10000 次调用) - 平均 257.30 ns/次
  AdaptiveSearch: 3392 μs (10000 次调用) - 平均 339.20 ns/次
  最快算法: FastSearch (2573 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.36x
    BinarySearch: 4.65x
    FastSearch: 1.00x ?
    AdaptiveSearch: 1.32x
  理论复杂度分析:
    LineSearch: O(n) = O(500) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(500) - 需要先收集索引
    FastSearch: O(n) = O(500) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: FastSearch可能有微小优势
--------------------------------------------------------------
数据规模: 1000 元素
  LineSearch: 16616 μs (10000 次调用) - 平均 1661.60 ns/次
  BinarySearch: 38554 μs (10000 次调用) - 平均 3855.40 ns/次
  FastSearch: 15230 μs (10000 次调用) - 平均 1523.00 ns/次
  AdaptiveSearch: 15648 μs (10000 次调用) - 平均 1564.80 ns/次
  最快算法: FastSearch (15230 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.09x
    BinarySearch: 2.53x
    FastSearch: 1.00x ?
    AdaptiveSearch: 1.03x
  理论复杂度分析:
    LineSearch: O(n) = O(1000) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(1000) - 需要先收集索引
    FastSearch: O(n) = O(1000) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: FastSearch可能有微小优势
--------------------------------------------------------------
数据规模: 2000 元素
  LineSearch: 39217 μs (10000 次调用) - 平均 3921.70 ns/次
  BinarySearch: 80967 μs (10000 次调用) - 平均 8096.70 ns/次
  FastSearch: 39931 μs (10000 次调用) - 平均 3993.10 ns/次
  AdaptiveSearch: 42789 μs (10000 次调用) - 平均 4278.90 ns/次
  最快算法: LineSearch (39217 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.00x ?
    BinarySearch: 2.06x
    FastSearch: 1.02x
    AdaptiveSearch: 1.09x
  理论复杂度分析:
    LineSearch: O(n) = O(2000) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(2000) - 需要先收集索引
    FastSearch: O(n) = O(2000) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 大数据集仍然推荐LineSearch
--------------------------------------------------------------
数据规模: 5000 元素
  LineSearch: 233426 μs (10000 次调用) - 平均 23342.60 ns/次
  BinarySearch: 938518 μs (10000 次调用) - 平均 93851.80 ns/次
  FastSearch: 244590 μs (10000 次调用) - 平均 24459.00 ns/次
  AdaptiveSearch: 245036 μs (10000 次调用) - 平均 24503.60 ns/次
  最快算法: LineSearch (233426 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.00x ?
    BinarySearch: 4.02x
    FastSearch: 1.05x
    AdaptiveSearch: 1.05x
  理论复杂度分析:
    LineSearch: O(n) = O(5000) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(5000) - 需要先收集索引
    FastSearch: O(n) = O(5000) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 大数据集仍然推荐LineSearch
--------------------------------------------------------------
数据规模: 10000 元素
  LineSearch: 857392 μs (10000 次调用) - 平均 85739.20 ns/次
  BinarySearch: 2008567 μs (10000 次调用) - 平均 200856.70 ns/次
  FastSearch: 851746 μs (10000 次调用) - 平均 85174.60 ns/次
  AdaptiveSearch: 850566 μs (10000 次调用) - 平均 85056.60 ns/次
  最快算法: AdaptiveSearch (850566 μs)
  性能对比 (相对于最快算法):
    LineSearch: 1.01x
    BinarySearch: 2.36x
    FastSearch: 1.00x
    AdaptiveSearch: 1.00x ?
  理论复杂度分析:
    LineSearch: O(n) = O(10000) - 实际最优(链表顺序访问)
    BinarySearch: O(n+log n) = O(10000) - 需要先收集索引
    FastSearch: O(n) = O(10000) - 优化的线性搜索

  算法特点分析:
    LineSearch: 简单直接，缓存友好，最少开销
    BinarySearch: 额外的索引收集开销，在链表上不适用
    FastSearch: 批量处理优化，减少函数调用开销
  建议: 大数据集仍然推荐LineSearch
--------------------------------------------------------------

 * ```
 *****************************************************************************/

// ==================== 前向声明 ====================

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
class NFShmHashTableWithList;

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListIterator;

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListConstIterator;

// 新增：链表迭代器前向声明
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListListIterator;

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListConstListIterator;

// ==================== 节点定义 ====================

/**
 * @brief Hash表节点结构
 * @tparam Val 存储的值类型
 *
 * 与STL不同，使用索引而非指针构建链表，适合共享内存环境。
 * STL通常使用指针链表，而这里使用索引链表提高共享内存兼容性。
 * 
 * 新增功能：支持插入顺序链表，用于维护插入顺序和LRU访问顺序
 */
template <class Val>
struct NFShmHashTableWithListNode
{
    /**
     * @brief 构造函数，根据创建模式选择初始化方式
     *
     * 与STL节点不同，支持共享内存的创建/恢复模式：
     * - 创建模式：初始化所有成员
     * - 恢复模式：从共享内存恢复，保持现有状态
     */
    NFShmHashTableWithListNode()
    {
        if (SHM_CREATE_MODE)
        {
            CreateInit();
        }
        else
        {
            ResumeInit();
        }
    }

    /// @brief 创建模式初始化
    int CreateInit()
    {
        m_valid = false;
        m_next = INVALID_ID;
        m_self = 0;
        m_listPrev = INVALID_ID; // 链表前驱索引
        m_listNext = INVALID_ID; // 链表后继索引
        return 0;
    }

    /// @brief 恢复模式初始化
    int ResumeInit()
    {
        return 0;
    }

    int m_next; ///< 下一个节点的索引（INVALID_ID表示链表末尾）
    Val m_value; ///< 存储的值
    bool m_valid; ///< 节点是否有效
    size_t m_self; ///< 节点自身索引（用于调试和验证）

    // 新增：链表指针，用于维护插入顺序和LRU访问顺序
    int m_listPrev; ///< 链表中前一个节点的索引（INVALID_ID表示链表头）
    int m_listNext; ///< 链表中下一个节点的索引（INVALID_ID表示链表尾）
};

// ==================== 迭代器实现 ====================

/**
 * @brief Hash表非常量迭代器
 * @tparam Val 值类型
 * @tparam Key 键类型
 * @tparam MAX_SIZE 最大容量
 * @tparam HashFcn 哈希函数类型
 * @tparam ExtractKey 键提取函数类型
 * @tparam EqualKey 键比较函数类型
 *
 * STL兼容性说明：
 * - 实现std::forward_iterator_tag，与STL unordered_map迭代器兼容
 * - 支持operator++, operator*, operator->等标准操作
 * - 与STL不同：基于索引实现，需要验证节点有效性
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListIterator
{
    // ==================== STL兼容类型定义 ====================
    typedef NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> Hashtable;
    typedef NFShmHashTableWithListIterator iterator;
    typedef NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> const_iterator;
    typedef NFShmHashTableWithListNode<Val> Node;

    /// @brief STL标准迭代器类型定义
    typedef std::forward_iterator_tag iterator_category; ///< 前向迭代器
    typedef Val value_type; ///< 值类型
    typedef ptrdiff_t difference_type; ///< 差值类型
    typedef size_t size_type; ///< 大小类型
    typedef Val& reference; ///< 引用类型
    typedef Val* pointer; ///< 指针类型

    // ==================== 成员变量 ====================
    Node* m_curNode; ///< 当前节点指针
    Hashtable* m_hashTable; ///< 所属哈希表指针
    static value_type m_staticError; ///< 错误时返回的静态对象

    // ==================== 构造函数 ====================

    /**
     * @brief 构造迭代器
     * @param n 节点指针
     * @param tab 哈希表指针
     */
    NFShmHashTableWithListIterator(Node* n, Hashtable* tab) : m_curNode(n), m_hashTable(tab)
    {
    }

    /// @brief 默认构造函数，创建无效迭代器
    NFShmHashTableWithListIterator() : m_curNode(nullptr), m_hashTable(nullptr)
    {
    }

    // ==================== STL兼容操作符 ====================

    /**
     * @brief 解引用操作符
     * @return 当前节点的值引用
     * @note 与STL行为一致，提供安全检查
     */
    reference operator*() const
    {
        CHECK_EXPR(m_curNode != nullptr, m_staticError, "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, m_staticError, "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return m_curNode->m_value;
    }

    /**
     * @brief 成员访问操作符
     * @return 当前节点值的指针
     * @note 与STL行为一致
     */
    pointer operator->() const
    {
        CHECK_EXPR(m_curNode != nullptr, &m_staticError, "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, &m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, &m_staticError, "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return &(m_curNode->m_value);
    }

    /// @brief 前置递增操作符，移动到下一个有效元素
    iterator& operator++();

    /// @brief 后置递增操作符
    iterator operator++(int);

    /// @brief 相等比较操作符
    bool operator==(const iterator& it) const { return m_curNode == it.m_curNode; }

    /// @brief 不等比较操作符
    bool operator!=(const iterator& it) const { return m_curNode != it.m_curNode; }
};

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
Val NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::m_staticError = Val();

/**
 * @brief Hash表常量迭代器
 * @note 与非常量迭代器类似，但提供const访问
 * @note 与STL const_iterator兼容
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListConstIterator
{
    // ==================== STL兼容类型定义 ====================
    typedef NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> Hashtable;
    typedef NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> iterator;
    typedef NFShmHashTableWithListConstIterator const_iterator;
    typedef NFShmHashTableWithListNode<Val> Node;

    typedef std::forward_iterator_tag iterator_category;
    typedef Val value_type;
    typedef ptrdiff_t difference_type;
    typedef size_t size_type;
    typedef const Val& reference; ///< 常量引用
    typedef const Val* pointer; ///< 常量指针

    // ==================== 成员变量 ====================
    const Node* m_curNode; ///< 当前节点常量指针
    const Hashtable* m_hashTable; ///< 所属哈希表常量指针
    static value_type m_staticError;

    // ==================== 构造函数 ====================

    NFShmHashTableWithListConstIterator(const Node* n, const Hashtable* tab) : m_curNode(n), m_hashTable(tab)
    {
    }

    NFShmHashTableWithListConstIterator() : m_curNode(nullptr), m_hashTable(nullptr)
    {
    }

    /**
     * @brief 从非常量迭代器构造
     * @param it 非常量迭代器
     * @note STL标准要求支持此转换
     */
    NFShmHashTableWithListConstIterator(const iterator& it) : m_curNode(it.m_curNode), m_hashTable(it.m_hashTable)
    {
    }

    // ==================== STL兼容操作符 ====================

    reference operator*() const
    {
        CHECK_EXPR(m_curNode != nullptr, m_staticError, "Const iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, m_staticError, "Const iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return m_curNode->m_value;
    }

    pointer operator->() const
    {
        CHECK_EXPR(m_curNode != nullptr, &m_staticError, "Const iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, &m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, &m_staticError, "Const iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return &(m_curNode->m_value);
    }

    const_iterator& operator++();
    const_iterator operator++(int);

    bool operator==(const const_iterator& it) const { return m_curNode == it.m_curNode; }
    bool operator!=(const const_iterator& it) const { return m_curNode != it.m_curNode; }
};

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
Val NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::m_staticError = Val();

// ==================== 主要Hash表类 ====================

/**
 * @brief 基于共享内存的Hash表实现
 * @tparam Val 值类型
 * @tparam Key 键类型
 * @tparam MAX_SIZE 最大容量（固定）
 * @tparam HashFcn 哈希函数类型
 * @tparam ExtractKey 从值中提取键的函数类型
 * @tparam EqualKey 键比较函数类型
 *
 * 设计特点：
 * 1. 固定容量，不支持动态扩容（与STL主要区别）
 * 2. 基于共享内存，支持进程间共享
 * 3. 使用索引链表而非指针链表
 * 4. API设计尽量兼容STL unordered_map/unordered_set
 *
 * 与STL unordered_map的主要差异：
 * - 容量限制：固定大小 vs 动态扩容
 * - 内存管理：共享内存 vs 堆内存
 * - 性能特征：无rehash开销 vs 动态性能优化
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
class NFShmHashTableWithList
{
public:
    // ==================== STL兼容类型定义 ====================

    typedef Key key_type; ///< 键类型
    typedef Val value_type; ///< 值类型
    typedef HashFcn hasher; ///< 哈希函数类型
    typedef EqualKey key_equal; ///< 键相等比较函数类型

    typedef size_t size_type; ///< 大小类型
    typedef ptrdiff_t difference_type; ///< 差值类型
    typedef value_type* pointer; ///< 指针类型
    typedef const value_type* const_pointer; ///< 常量指针类型
    typedef value_type& reference; ///< 引用类型
    typedef const value_type& const_reference; ///< 常量引用类型

    typedef NFShmHashTableWithListNode<Val> Node; ///< 节点类型

private:
    // ==================== 内存管理 ====================

    /// @brief 对齐存储，确保节点内存布局正确
    typedef typename std::aligned_storage<sizeof(Node), alignof(Node)>::type AlignedStorage;

    AlignedStorage m_buckets[MAX_SIZE]; ///< 节点存储区域
    int m_bucketsFirstIdx[MAX_SIZE]; ///< 每个桶的首节点索引
    int m_firstFreeIdx; ///< 空闲链表头节点索引
    size_type m_size; ///< 当前元素数量
    int8_t m_init; ///< 初始化状态
    hasher m_hash; ///< 哈希函数对象
    key_equal m_equals; ///< 键比较函数对象
    ExtractKey m_getKey; ///< 键提取函数对象
    static value_type m_staticError; ///< 错误返回值

    // 新增：链表管理成员变量
    int m_listHead; ///< 插入顺序链表头节点索引（INVALID_ID表示空链表）
    int m_listTail; ///< 插入顺序链表尾节点索引（INVALID_ID表示空链表）
    bool m_enableLRU; ///< LRU功能开关，当为true时find/count操作会将节点移到链表尾部
    bool m_enableInsertHead; /// 插入新节点时是否插入到链表头部（默认插入尾部）
private:
    /// @brief 获取桶数组指针
    Node* GetBuckets() { return reinterpret_cast<Node*>(m_buckets); }
    /// @brief 获取桶数组常量指针
    const Node* GetBuckets() const { return reinterpret_cast<const Node*>(m_buckets); }

private:
    /**
     * @brief 创建新节点
     * @return 新节点指针，失败返回nullptr
     * @note 从空闲链表中获取节点，与STL的allocator分配不同
     */
    Node* CreateNode();

    /**
     * @brief 回收节点到空闲链表
     * @param p 要回收的节点指针
     * @note 不释放内存，而是标记为无效并加入空闲链表
     */
    void RecycleNode(Node* p);

public:
    // ==================== 迭代器类型定义 ====================

    typedef NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> iterator;
    typedef NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> const_iterator;

    // 新增：链表迭代器类型定义
    typedef NFShmHashTableWithListListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> list_iterator;
    typedef NFShmHashTableWithListConstListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> const_list_iterator;

    friend struct NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>;
    friend struct NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>;
    friend struct NFShmHashTableWithListListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>;
    friend struct NFShmHashTableWithListConstListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>;

public:
    // ==================== 构造函数和析构函数 ====================

    /**
     * @brief 构造函数
     * @note 根据SHM_CREATE_MODE决定创建或恢复模式
     */
    NFShmHashTableWithList();

    /**
     * @brief 拷贝构造函数
     * @param ht 源哈希表
     */
    NFShmHashTableWithList(const NFShmHashTableWithList& ht);

    /**
     * @brief 赋值操作符
     * @param ht 源哈希表
     * @return 自身引用
     */
    NFShmHashTableWithList& operator=(const NFShmHashTableWithList& ht);

    /**
     * @brief 析构函数
     */
    virtual ~NFShmHashTableWithList();

    // ==================== 共享内存特有接口 ====================

    /**
     * @brief 创建模式初始化（共享内存特有）
     * @return 0表示成功，-1表示失败
     * @note 与STL对比：
     *       - STL: 无对应概念，构造函数即完成初始化
     *       - NFShmHashTableWithList: 支持共享内存CREATE/RESUME两阶段初始化
     *       - 用于共享内存首次创建时的初始化
     *       - 初始化桶数组、空闲链表和插入顺序链表
     *       - 所有节点标记为无效状态，建立空闲链表
     *       - 初始化LRU状态和链表头尾指针
     *       - 在SHM_CREATE_MODE下自动调用
     *
     * 使用示例：
     * ```cpp
     * typedef std::pair<int, std::string> KeyValue;
     * struct KeyExtractor { int operator()(const KeyValue& kv) const { return kv.first; } };
     *
     * NFShmHashTableWithList<KeyValue, int, 100, std::hash<int>, KeyExtractor, std::equal_to<int>> table;
     * if (table.CreateInit() == 0) {
     *     // 创建成功，可以开始使用
     *     table.insert_unique(KeyValue(42, "value"));
     *     table.enable_lru();  // 启用LRU功能
     * }
     * ```
     */
    int CreateInit();

    /**
     * @brief 恢复模式初始化（共享内存特有）
     * @return 0表示成功，-1表示失败
     * @note 与STL对比：
     *       - STL: 无对应概念
     *       - NFShmHashTableWithList: 用于从已存在的共享内存恢复容器状态
     *       - 不清空现有数据，恢复哈希表和链表结构
     *       - 重新建立节点间的链接关系（哈希链表和插入顺序链表）
     *       - 验证链表完整性和数据一致性
     *       - 恢复LRU状态和链表头尾指针
     *       - 对非平凡构造类型执行placement构造
     *       - 进程重启后恢复共享内存数据使用
     *
     * 使用示例：
     * ```cpp
     * // 进程重启后恢复哈希表
     * NFShmHashTableWithList<KeyValue, int, 100, std::hash<int>, KeyExtractor, std::equal_to<int>> table;
     * if (table.ResumeInit() == 0) {
     *     // 恢复成功，数据已可用
     *     std::cout << "Recovered " << table.size() << " elements" << std::endl;
     *
     *     // 检查LRU状态
     *     if (table.is_lru_enabled()) {
     *         std::cout << "LRU mode is enabled" << std::endl;
     *     }
     *
     *     // 验证链表完整性
     *     if (table.ValidateListIntegrity()) {
     *         std::cout << "List integrity: OK" << std::endl;
     *     }
     * }
     * ```
     */
    int ResumeInit();

    /**
     * @brief 就地初始化
     * @note 使用placement new重新构造对象
     */
    void Init();

    // ==================== 容量相关接口（STL兼容） ====================

    /**
     * @brief 获取当前元素数量
     * @return 元素数量
     * @note 与STL unordered_map::size()兼容
     */
    size_type size() const;

    /**
     * @brief 获取最大容量
     * @return 最大容量MAX_SIZE
     * @note 与STL不同，返回固定值而非理论最大值
     */
    size_type max_size() const;

    /**
     * @brief 判断是否为空
     * @return true表示空
     * @note 与STL unordered_map::empty()兼容
     */
    bool empty() const;

    /**
     * @brief 判断是否已满
     * @return true表示已满
     * @note STL容器没有此接口，固定容量特有
     */
    bool full() const;

    /**
     * @brief 获取剩余容量
     * @return 剩余可用空间
     * @note STL容器没有此接口
     */
    size_t left_size() const;

    // ==================== 节点访问接口 ====================

    /**
     * @brief 根据索引获取有效节点
     * @param idx 节点索引
     * @return 节点指针，无效返回nullptr
     */
    Node* GetNode(int idx);

    /**
     * @brief 根据索引获取有效节点（常量版本）
     * @param idx 节点索引
     * @return 常量节点指针，无效返回nullptr
     */
    const Node* GetNode(int idx) const;

    /**
     * @brief 根据索引创建迭代器
     * @param idx 节点索引
     * @return 迭代器
     */
    iterator get_iterator(int idx);

    /**
     * @brief 根据索引创建常量迭代器
     * @param idx 节点索引
     * @return 常量迭代器
     */
    const_iterator get_iterator(int idx) const;

    // ==================== STL兼容交换接口 ====================

    /**
     * @brief 交换两个哈希表的内容
     * @param other 另一个哈希表
     * @note 与STL unordered_map::swap()兼容
     */
    void swap(NFShmHashTableWithList& other) noexcept;

    // ==================== STL兼容迭代器接口 ====================

    /**
     * @brief 获取起始迭代器
     * @return 指向第一个元素的迭代器
     * @note 与STL unordered_map::begin()兼容
     */
    iterator begin();

    /**
     * @brief 获取结束迭代器
     * @return 指向末尾的迭代器
     * @note 与STL unordered_map::end()兼容
     */
    iterator end();

    /**
     * @brief 获取常量起始迭代器
     * @return 指向第一个元素的常量迭代器
     * @note 与STL unordered_map::begin() const兼容
     */
    const_iterator begin() const;

    /**
     * @brief 获取常量结束迭代器
     * @return 指向末尾的常量迭代器
     * @note 与STL unordered_map::end() const兼容
     */
    const_iterator end() const;

    // ==================== 链表迭代器接口（新增） ====================

    /**
     * @brief 获取链表起始迭代器（按插入顺序）
     * @return 指向链表第一个元素的迭代器
     * @note 与STL对比：
     *       - STL: 无对应接口，std::unordered_map只有哈希顺序遍历
     *       - NFShmHashTableWithList: 特有功能，按插入顺序遍历
     *       - 提供与begin()不同的遍历方式：插入顺序 vs 哈希顺序
     *       - 时间复杂度：O(1)
     *       - 支持与标准迭代器相同的操作（++、*、->等）
     *       - 适用于FIFO队列、LRU缓存、调试分析等场景
     *
     * 使用场景对比：
     * ```cpp
     * typedef std::pair<int, std::string> KeyValue;
     * struct KeyExtractor { int operator()(const KeyValue& kv) const { return kv.first; } };
     *
     * NFShmHashTableWithList<KeyValue, int, 100,
     *                        std::hash<int>, KeyExtractor,
     *                        std::equal_to<int>> table;
     *
     * // 插入数据
     * table.insert_unique(KeyValue(3, "third"));
     * table.insert_unique(KeyValue(1, "first"));
     * table.insert_unique(KeyValue(2, "second"));
     *
     * // 哈希顺序遍历（类似STL）
     * std::cout << "Hash order:" << std::endl;
     * for (auto it = table.begin(); it != table.end(); ++it) {
     *     std::cout << it->first << ": " << it->second << std::endl;
     * }
     * // 可能输出：1: first, 2: second, 3: third (取决于哈希函数)
     *
     * // 插入顺序遍历（特有功能）
     * std::cout << "Insert order:" << std::endl;
     * for (auto it = table.list_begin(); it != table.list_end(); ++it) {
     *     std::cout << it->first << ": " << it->second << std::endl;
     * }
     * // 输出：3: third, 1: first, 2: second (严格按插入顺序)
     *
     * // C++11 范围for循环支持
     * for (const auto& item : table) {
     *     // 哈希顺序遍历
     * }
     *
     * // 链表遍历需要显式使用迭代器
     * for (auto it = table.list_begin(); it != table.list_end(); ++it) {
     *     // 插入顺序遍历
     * }
     * ```
     */
    list_iterator list_begin();

    /**
     * @brief 获取链表结束迭代器
     * @return 指向链表末尾的迭代器
     */
    list_iterator list_end();

    /**
     * @brief 获取常量链表起始迭代器
     * @return 指向链表第一个元素的常量迭代器
     */
    const_list_iterator list_begin() const;

    /**
     * @brief 获取常量链表结束迭代器
     * @return 指向链表末尾的常量迭代器
     */
    const_list_iterator list_end() const;

    /**
     * @brief 获取常量链表起始迭代器（C++11风格）
     * @return 指向链表第一个元素的常量迭代器
     */
    const_list_iterator list_cbegin() const;

    /**
     * @brief 获取常量链表结束迭代器（C++11风格）
     * @return 指向链表末尾的常量迭代器
     */
    const_list_iterator list_cend() const;

    // ==================== LRU功能控制接口（新增） ====================

    /**
     * @brief 启用LRU功能
     * @note 启用后，find/count操作会将访问的节点移动到链表尾部
     */
    void enable_lru() { m_enableLRU = true; }

    /**
     * @brief 禁用LRU功能
     * @note 禁用后，find/count操作不会移动节点位置
     */
    void disable_lru() { m_enableLRU = false; }

    /**
     * @brief 检查LRU功能是否启用
     * @return true表示启用，false表示禁用
     */
    bool is_lru_enabled() const { return m_enableLRU; }

    /**
     * @brief 设置插入新节点时是否插入到链表头部
     */
    void enable_insert_head() { m_enableInsertHead = true; }

    /**
     * @brief 禁用插入新节点时是否插入到链表头部
     */
    void disable_insert_head() { m_enableInsertHead = false; }

    /**
     * @brief 是否插入新节点时是否插入到链表头部
     */
    bool is_insert_head_enable() const { return m_enableInsertHead; }

    // ==================== 友元比较操作符 ====================

    template <class Vl, class Ky, int MaxSize, class HF, class Ex, class Eq>
    friend bool operator==(const NFShmHashTableWithList<Vl, Ky, MaxSize, HF, Ex, Eq>&, const NFShmHashTableWithList<Vl, Ky, MaxSize, HF, Ex, Eq>&);

public:
    // ==================== 桶接口（STL兼容） ====================

    /**
     * @brief 获取桶数量
     * @return 桶数量（固定为MAX_SIZE）
     * @note 与STL unordered_map::bucket_count()兼容，但返回固定值
     */
    size_type bucket_count() const;

    /**
     * @brief 获取最大桶数量
     * @return 最大桶数量（固定为MAX_SIZE）
     * @note 与STL unordered_map::max_bucket_count()兼容
     */
    size_type max_bucket_count() const;

    /**
     * @brief 获取指定桶中的元素数量
     * @param bucket 桶索引
     * @return 该桶中的元素数量
     * @note 与STL unordered_map::bucket_size()类似
     */
    size_type elems_in_bucket(size_type bucket) const;

    // ==================== 插入接口（STL兼容） ====================

    /**
     * @brief 插入唯一元素
     * @param obj 要插入的值
     * @return pair<iterator, bool>，迭代器指向元素，bool表示是否插入成功
     * @note 与STL unordered_map::insert()兼容
     */
    std::pair<iterator, bool> insert_unique(const value_type& obj);

    /**
     * @brief 插入允许重复的元素
     * @param obj 要插入的值
     * @return 指向插入元素的迭代器
     * @note 与STL unordered_multimap::insert()兼容
     */
    iterator insert_equal(const value_type& obj);

    /**
     * @brief 插入唯一元素（无扩容版本）
     * @param obj 要插入的值
     * @return pair<iterator, bool>
     * @note 内部使用，不触发扩容检查
     */
    std::pair<iterator, bool> insert_unique_noresize(const value_type& obj);

    /**
     * @brief 插入允许重复元素（无扩容版本）
     * @param obj 要插入的值
     * @return 指向插入元素的迭代器
     */
    iterator insert_equal_noresize(const value_type& obj);

    // ==================== 排序插入接口（新增） ====================

    /**
     * @brief 排序插入唯一元素（使用默认升序）
     * @param obj 要插入的值
     * @return pair<iterator, bool>，迭代器指向元素，bool表示是否插入成功
     * @note 如果启用了排序插入功能，会在正确位置插入以保持链表排序
     * @note 如果未启用排序插入功能，等同于普通insert_unique
     * @note 时间复杂度：O(1)哈希定位 + O(n)链表遍历定位插入位置
     */
    std::pair<iterator, bool> insert_list_sorted_unique(const value_type& obj)
    {
        return insert_list_sorted_unique(obj, std::less<value_type>());
    }

    /**
     * @brief 排序插入唯一元素（使用自定义比较器）
     * @param obj 要插入的值
     * @param comp 比较函数对象
     * @return pair<iterator, bool>，迭代器指向元素，bool表示是否插入成功
     * @note 使用自定义比较器进行排序插入，忽略全局排序方向设置
     * @note 时间复杂度：O(1)哈希定位 + O(n)链表遍历定位插入位置
     *
     * 使用示例：
     * ```cpp
     * // 按值的某个字段降序插入
     * table.insert_list_sorted_unique(obj, [](const auto& a, const auto& b) {
     *     return a.priority > b.priority;  // 降序
     * });
     *
     * // 按复合条件排序
     * table.insert_list_sorted_unique(obj, [](const auto& a, const auto& b) {
     *     if (a.category != b.category)
     *         return a.category < b.category;
     *     return a.value < b.value;
     * });
     * ```
     */
    template <class Compare>
    std::pair<iterator, bool> insert_list_sorted_unique(const value_type& obj, Compare comp);

    /**
     * @brief 排序插入允许重复的元素（使用默认升序）
     * @param obj 要插入的值
     * @return 指向插入元素的迭代器
     * @note 如果启用了排序插入功能，会在正确位置插入以保持链表排序
     * @note 如果未启用排序插入功能，等同于普通insert_equal
     * @note 时间复杂度：O(1)哈希定位 + O(n)链表遍历定位插入位置
     */
    iterator insert_list_sorted_equal(const value_type& obj)
    {
        return insert_list_sorted_equal(obj, std::less<value_type>());
    }

    /**
     * @brief 排序插入允许重复的元素（使用自定义比较器）
     * @param obj 要插入的值
     * @param comp 比较函数对象
     * @return 指向插入元素的迭代器
     * @note 使用自定义比较器进行排序插入，忽略全局排序方向设置
     * @note 允许插入重复元素，按比较器确定的顺序插入
     * @note 时间复杂度：O(1)哈希定位 + O(n)链表遍历定位插入位置
     */
    template <class Compare>
    iterator insert_list_sorted_equal(const value_type& obj, Compare comp);

    void move_to_list_sorted(iterator iter)
    {
        return move_to_list_sorted(iter, std::less<value_type>());
    }

    template <class Compare>
    void move_to_list_sorted(iterator iter, Compare comp)
    {
        MoveToNodeSorted(iter, comp);
    }

    void move_to_list_sorted(const_iterator iter)
    {
        return move_to_list_sorted(iter, std::less<value_type>());
    }

    template <class Compare>
    void move_to_list_sorted(const_iterator iter, Compare comp)
    {
        MoveToNodeSorted(iter, comp);
    }

    void move_to_list_sorted(list_iterator iter)
    {
        return move_to_list_sorted(iter, std::less<value_type>());
    }

    template <class Compare>
    void move_to_list_sorted(list_iterator iter, Compare comp)
    {
        MoveToNodeSorted(iter, comp);
    }

    void move_to_list_sorted(const_list_iterator iter)
    {
        return move_to_list_sorted(iter, std::less<value_type>());
    }

    template <class Compare>
    void move_to_list_sorted(const_list_iterator iter, Compare comp)
    {
        MoveToNodeSorted(iter, comp);
    }

    // ==================== 范围插入接口 ====================

    template <class InputIterator>
    void insert_unique(InputIterator f, InputIterator l);

    template <class InputIterator>
    void insert_equal(InputIterator f, InputIterator l);

    template <class InputIterator>
    void insert_unique(InputIterator f, InputIterator l, std::input_iterator_tag);

    template <class InputIterator>
    void insert_equal(InputIterator f, InputIterator l, std::input_iterator_tag);

    template <class ForwardIterator>
    void insert_unique(ForwardIterator f, ForwardIterator l, std::forward_iterator_tag);

    template <class ForwardIterator>
    void insert_equal(ForwardIterator f, ForwardIterator l, std::forward_iterator_tag);

    void insert_unique(const value_type* f, const value_type* l);
    void insert_equal(const value_type* f, const value_type* l);
    void insert_unique(const_iterator f, const_iterator l);
    void insert_equal(const_iterator f, const_iterator l);

    // ==================== 查找接口（STL兼容） ====================

    /**
     * @brief 查找或插入元素
     * @param obj 要查找或插入的值
     * @return 元素的引用
     * @note 类似STL unordered_map::operator[]的行为
     */
    reference find_or_insert(const value_type& obj);

    /**
     * @brief 查找元素
     * @param key 要查找的键
     * @return 指向元素的迭代器，未找到返回end()
     * @note 与STL对比：
     *       - STL: std::unordered_map::find() 行为基本一致
     *       - NFShmHashTableWithList: 额外的LRU功能支持
     *       - 时间复杂度：O(1)平均，O(n)最坏（链表长度）
     *       - 未找到时返回end()，而非抛出异常
     *       - **LRU增强**：当启用LRU时，查找成功会将节点移到链表尾部
     *       - 支持自定义哈希函数和比较函数
     *
     * LRU行为说明：
     * - LRU禁用时：查找操作不改变插入顺序链表
     * - LRU启用时：查找成功的元素自动移到链表尾部（标记为最近使用）
     *
     * 与STL用法对比：
     * ```cpp
     * // STL用法（无LRU功能）
     * std::unordered_map<std::string, int> stdMap;
     * stdMap["apple"] = 100;
     * auto it1 = stdMap.find("apple");
     * if (it1 != stdMap.end()) {
     *     std::cout << "Found: " << it1->second << std::endl;
     * }
     *
     * // NFShmHashTableWithList用法（支持LRU）
     * typedef std::pair<std::string, int> KeyValue;
     * struct KeyExtractor { const std::string& operator()(const KeyValue& kv) const { return kv.first; } };
     *
     * NFShmHashTableWithList<KeyValue, std::string, 100,
     *                        std::hash<std::string>, KeyExtractor,
     *                        std::equal_to<std::string>> table;
     * table.insert_unique(KeyValue("apple", 100));
     *
     * // 不启用LRU（类似STL行为）
     * table.disable_lru();
     * auto it2 = table.find("apple");  // 查找不影响插入顺序
     *
     * // 启用LRU（增强功能）
     * table.enable_lru();
     * auto it3 = table.find("apple");  // 查找成功，"apple"移到链表尾部
     * if (it3 != table.end()) {
     *     std::cout << "Found: " << it3->second << std::endl;
     *     // 此时"apple"成为最近访问的元素
     * }
     * ```
     */
    iterator find(const key_type& key);

    /**
     * @brief 查找元素（常量版本）
     * @param key 要查找的键
     * @return 指向元素的常量迭代器
     * @note 与STL unordered_map::find() const兼容
     */
    const_iterator find(const key_type& key) const;

    /**
     * @brief 统计指定键的元素数量
     * @param key 要统计的键
     * @return 元素数量
     * @note 与STL对比：
     *       - STL: std::unordered_map::count() 完全兼容
     *       - NFShmHashTableWithList: 额外的LRU功能支持
     *       - 对于insert_unique插入的元素，结果为0或1
     *       - 对于insert_equal插入的元素，可能大于1
     *       - 时间复杂度：O(1)平均，O(n)最坏
     *       - **LRU增强**：当启用LRU时，统计过程中会触发LRU更新
     *
     * LRU行为说明：
     * - LRU禁用时：统计操作不改变插入顺序链表
     * - LRU启用时：每个匹配的元素都会移到链表尾部
     *
     * 与STL用法对比：
     * ```cpp
     * // STL用法
     * std::unordered_multimap<int, std::string> stdMultiMap;
     * stdMultiMap.insert({42, "first"});
     * stdMultiMap.insert({42, "second"});
     * std::cout << "Count: " << stdMultiMap.count(42) << std::endl;  // 输出：2
     *
     * // NFShmHashTableWithList用法（支持LRU）
     * typedef std::pair<int, std::string> KeyValue;
     * struct KeyExtractor { int operator()(const KeyValue& kv) const { return kv.first; } };
     *
     * NFShmHashTableWithList<KeyValue, int, 100,
     *                        std::hash<int>, KeyExtractor,
     *                        std::equal_to<int>> table;
     * table.insert_equal(KeyValue(42, "first"));
     * table.insert_equal(KeyValue(42, "second"));
     *
     * // 不启用LRU（类似STL行为）
     * table.disable_lru();
     * std::cout << "Count: " << table.count(42) << std::endl;  // 输出：2，不影响插入顺序
     *
     * // 启用LRU（增强功能）
     * table.enable_lru();
     * std::cout << "Count: " << table.count(42) << std::endl;  // 输出：2，所有匹配元素移到链表尾部
     * ```
     */
    size_type count(const key_type& key) const;

    /**
     * @brief 获取指定键的元素范围
     * @param key 要查找的键
     * @return pair<iterator, iterator>表示范围
     * @note 与STL unordered_map::equal_range()兼容
     */
    std::pair<iterator, iterator> equal_range(const key_type& key);

    /**
     * @brief 获取指定键的元素范围（常量版本）
     * @param key 要查找的键
     * @return pair<const_iterator, const_iterator>表示范围
     */
    std::pair<const_iterator, const_iterator> equal_range(const key_type& key) const;

    value_type& at(const key_type& key);
    const value_type& at(const key_type& key) const;

    // ==================== 删除接口（STL兼容） ====================

    /**
     * @brief 根据键删除元素
     * @param key 要删除的键
     * @return 删除的元素数量
     * @note 与STL unordered_map::erase()兼容
     */
    size_type erase(const key_type& key);

    /**
     * @brief 根据迭代器删除元素
     * @param it 指向要删除元素的迭代器
     * @return 指向下一个元素的迭代器
     * @note 与STL unordered_map::erase()兼容
     */
    iterator erase(iterator it);

    /**
     * @brief 根据迭代器删除元素
     * @param it 指向要删除元素的迭代器
     * @return 指向下一个元素的迭代器
     * @note 与STL unordered_map::erase()兼容
     */
    list_iterator erase(list_iterator it);

    /**
     * @brief 根据常量迭代器删除元素
     * @param it 指向要删除元素的常量迭代器
     * @return 指向下一个元素的常量迭代器
     */
    iterator erase(const_iterator it);

    /**
     * @brief 根据常量迭代器删除元素
     * @param it 指向要删除元素的常量迭代器
     * @return 指向下一个元素的常量迭代器
     */
    list_iterator erase(const_list_iterator it);

    /**
     * @brief 删除指定范围的元素
     * @param first 起始迭代器
     * @param last 结束迭代器
     * @note 与STL unordered_map::erase()兼容
     */
    iterator erase(iterator first, iterator last);

    /**
     * @brief 删除指定范围的元素（常量版本）
     * @param first 起始常量迭代器
     * @param last 结束常量迭代器
     */
    iterator erase(const_iterator first, const_iterator last);

    // ==================== 容量管理接口 ====================

    /**
     * @brief 调整大小提示
     * @param numElementsHint 元素数量提示
     * @note 与STL接口兼容但实际不执行操作（固定容量）
     */
    void resize(size_type numElementsHint);

    /**
     * @brief 清空所有元素
     * @note 与STL对比：
     *       - STL: std::unordered_map::clear() 行为基本一致
     *       - NFShmHashTableWithList: 额外清理插入顺序链表和LRU状态
     *       - 删除所有元素，重置为空状态
     *       - 所有节点回收到空闲链表，可重复使用
     *       - 桶数组重置为空状态，所有桶指向-1
     *       - **链表特有**：重置插入顺序链表头尾指针
     *       - **LRU特有**：保持LRU开关状态不变
     *       - 时间复杂度：O(n)，n为当前元素数量
     *       - 操作后size()返回0，full()返回false
     *
     * 清理内容对比：
     * ```
     * STL clear()清理内容：
     * - 删除所有元素
     * - 重置桶数组
     * - 释放动态分配的内存
     *
     * NFShmHashTableWithList clear()清理内容：
     * - 删除所有元素 ✓
     * - 重置桶数组 ✓
     * - 回收节点到空闲链表 ✓ (而非释放内存)
     * - 重置插入顺序链表 ✓ (STL无此功能)
     * - 保持LRU开关状态 ✓ (STL无此功能)
     * - 保持固定容量不变 ✓ (STL可能改变桶数量)
     * ```
     *
     * 与STL用法对比：
     * ```cpp
     * // STL用法
     * std::unordered_map<int, std::string> stdMap;
     * stdMap[1] = "one";
     * stdMap[2] = "two";
     * stdMap.clear();  // 清空所有元素
     * assert(stdMap.empty());
     *
     * // NFShmHashTableWithList用法
     * typedef std::pair<int, std::string> KeyValue;
     * struct KeyExtractor { int operator()(const KeyValue& kv) const { return kv.first; } };
     *
     * NFShmHashTableWithList<KeyValue, int, 100,
     *                        std::hash<int>, KeyExtractor,
     *                        std::equal_to<int>> table;
     *
     * table.enable_lru();  // 启用LRU
     * table.insert_unique(KeyValue(1, "one"));
     * table.insert_unique(KeyValue(2, "two"));
     *
     * // 清空前状态检查
     * assert(table.size() == 2);
     * assert(!table.empty());
     * assert(table.is_lru_enabled());
     *
     * table.clear();  // 清空所有元素和链表
     *
     * // 清空后状态检查
     * assert(table.empty());
     * assert(table.size() == 0);
     * assert(table.left_size() == table.max_size());
     * assert(table.is_lru_enabled());  // LRU状态保持不变
     * assert(table.list_begin() == table.list_end());  // 链表为空
     *
     * // 可以立即重新使用
     * table.insert_unique(KeyValue(3, "three"));
     * ```
     */
    void clear();

    // ==================== 调试和诊断接口 ====================

    /**
     * @brief 打印哈希表结构信息
     * @note 调试用，显示桶链表结构
     */
    void print_structure() const;

    /**
     * @brief 打印详细信息
     * @note 调试用，显示所有节点状态
     */
    void print_detailed() const;

    /**
     * @brief 打印简化信息
     * @note 调试用，仅显示非空桶
     */
    void print_simple() const;

    /**
     * @brief 打印链表信息
     * @note 调试用，专门显示插入顺序链表的详细信息
     */
    void print_list() const;

    /**
     * @brief 验证链表完整性（调试用）
     * @return true表示链表完整性正确，false表示存在问题
     * @note 用于调试和错误诊断
     */
    bool ValidateListIntegrity() const;

public:
    /**
     * @brief 智能选择最优排序算法
     * @note 根据数据规模自动选择最适合的排序算法：
     * @note 这是推荐的默认排序方法，能够在各种情况下提供最佳性能
     */
    void sort_list()
    {
        SortList();
    }

    /**
     * @brief 智能选择最优排序算法（使用自定义比较器）
     * @param comp 比较函数对象
     * @note 根据数据规模自动选择最适合的排序算法
     */
    template <class StrictWeakOrdering>
    void sort_list(StrictWeakOrdering comp)
    {
        SortList(comp);
    }

    template <class StrictWeakOrdering>
    void move_to_list_node_front(const_iterator iter, StrictWeakOrdering compareFunc)
    {
        MoveToNodeFront(iter, compareFunc);
    }

    template <class StrictWeakOrdering>
    void move_to_list_node_front(const_list_iterator iter, StrictWeakOrdering compareFunc)
    {
        MoveToNodeFront(iter, compareFunc);
    }

    template <class StrictWeakOrdering>
    void move_to_list_node_back(const_iterator iter, StrictWeakOrdering compareFunc)
    {
        MoveToNodeBack(iter, compareFunc);
    }

    template <class StrictWeakOrdering>
    void move_to_list_node_back(const_list_iterator iter, StrictWeakOrdering compareFunc)
    {
        MoveToNodeBack(iter, compareFunc);
    }

private:
    // ==================== 内部实现函数 ====================

    /**
     * @brief 初始化桶数组
     * @note 设置空闲链表和桶索引数组
     */
    void InitializeBuckets();

    /**
     * @brief 根据键计算桶索引
     * @param key 键值
     * @return 桶索引
     */
    size_type BktNumKey(const key_type& key) const;

    /**
     * @brief 根据值计算桶索引
     * @param obj 值对象
     * @return 桶索引
     */
    size_type BktNum(const value_type& obj) const;

    /**
     * @brief 根据键和桶数量计算桶索引
     * @param key 键值
     * @param n 桶数量
     * @return 桶索引
     */
    size_type BktNumKey(const key_type& key, size_t n) const;

    /**
     * @brief 根据值和桶数量计算桶索引
     * @param obj 值对象
     * @param n 桶数量
     * @return 桶索引
     */
    size_type MBktNum(const value_type& obj, size_t n) const;

    /**
     * @brief 创建新节点并初始化
     * @param obj 要存储的值
     * @return 新节点指针，失败返回nullptr
     */
    Node* NewNode(const value_type& obj);

    /**
     * @brief 删除节点并回收
     * @param pNode 要删除的节点指针
     */
    void DeleteNode(Node* pNode);

    /**
     * @brief 删除桶中指定范围的节点
     * @param n 桶索引
     * @param first 起始节点
     * @param last 结束节点
     */
    void EraseBucket(size_type n, Node* first, Node* last);

    /**
     * @brief 删除桶中从头到指定节点的所有节点
     * @param n 桶索引
     * @param last 结束节点
     */
    void EraseBucket(size_type n, Node* last);

    /**
     * @brief 从另一个哈希表复制内容
     * @param ht 源哈希表
     */
    void CopyFrom(const NFShmHashTableWithList& ht);

    // ==================== 链表管理函数（新增） ====================
public:
    template <class Compare>
    void MoveToNodeFront(const_iterator iter, Compare comp);
    template <class Compare>
    void MoveToNodeFront(const_list_iterator iter, Compare comp);
    template <class Compare>
    void MoveToNodeBack(const_iterator iter, Compare comp);
    template <class Compare>
    void MoveToNodeBack(const_list_iterator iter, Compare comp);

    // ==================== 有序链表优化版本（新增） ====================

    /**
     * @brief 有序链表中的优化移动到前面（使用二分搜索）
     * @param iter 要移动的元素迭代器
     * @param comp 比较函数，用于确定插入位置
     * @note 前提条件：链表必须已经有序
     * @note 时间复杂度：O(log n) + O(1)移动操作
     * @note 适用场景：已知链表有序的排序插入操作
     *
     * 性能改进说明：
     * - LineSearchInsertPosition: 时间复杂度O(n)，但缓存友好，适合小数据集(≤16)
     * - BinarySearchInsertPosition: 时间复杂度O(log n)，使用栈分配避免动态内存，适合中等数据集(17-128)
     * - FastSearchInsertPosition: 优化的混合算法，适合较大数据集(129-512)
     * - AdaptiveSearchInsertPosition: 自适应策略，根据数据规模智能选择最优算法
     */
    template <class Compare>
    void MoveToNodeSorted(const_iterator iter, Compare comp);

    /**
     * @brief 有序链表中的优化移动到前面（链表迭代器版本）
     */
    template <class Compare>
    void MoveToNodeSorted(const_list_iterator iter, Compare comp);

    /**
     * @brief 智能选择最优排序算法
     * @note 根据数据规模自动选择最适合的排序算法：
     * @note 这是推荐的默认排序方法，能够在各种情况下提供最佳性能
     */
    void SortList()
    {
        SortListMergeFast();
    }

    /**
     * @brief 智能选择最优排序算法（使用自定义比较器）
     * @param comp 比较函数对象
     * @note 根据数据规模自动选择最适合的排序算法
     */
    template <class StrictWeakOrdering>
    void SortList(StrictWeakOrdering comp)
    {
        SortListMergeFast(comp);
    }

    /**
     * @brief 链表排序（使用默认比较器）
     * @note 与STL对比：
     *       - STL: std::list::sort() 直接在链表上排序，时间复杂度O(n log n)
     *       - NFShmHashTableWithList: 类似接口，使用插入排序算法
     *       - 内部实现：基于已有的链表移动功能实现插入排序
     *       - 排序过程中保持哈希表功能正确性
     *       - 迭代器在排序后保持有效性
     *       - 使用默认比较器std::less<Val>
     *       - 时间复杂度：O(n²)，空间复杂度：O(1)
     *       - 稳定排序：相等元素保持原有顺序
     *
     * 与STL用法对比：
     * ```cpp
     * // STL用法
     * std::list<int> stdList = {3, 1, 4, 1, 5};
     * stdList.sort();  // 直接在原链表上排序
     *
     * // NFShmHashTableWithList用法
     * NFShmHashTableWithList<...> table;
     * table.sort();     // 同样的接口，插入排序实现
     * // 结果：链表按升序排列 {1, 1, 3, 4, 5}
     * ```
     *
     * 插入排序特点：
     * - 对于小数据集或近似有序的数据效率很高
     * - 算法简单，在链表上实现自然且高效
     * - 稳定排序算法，保持相等元素的相对顺序
     * - 原地排序，只需要O(1)额外空间
     * - 自适应算法，对已排序数据复杂度接近O(n)
     */
    void SortListInsert()
    {
        SortListInsert(std::less<Val>());
    }

    /**
     * @brief 链表排序（使用自定义比较器）
     * @param comp 比较函数对象
     * @note 与STL对比：
     *       - STL: std::list::sort() 完全兼容，支持自定义比较器
     *       - NFShmHashTableWithList: 行为完全一致
     *       - 支持lambda表达式、函数指针、函数对象等
     *       - 使用插入排序算法，时间复杂度O(n²)
     *       - 保证排序的稳定性（相等元素保持原有顺序）
     *       - 原地排序，空间复杂度O(1)
     *       - 对小数据集和近似有序数据效率高
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     *
     * // 降序排序
     * table.sort(std::greater<Val>());
     *
     * // 使用lambda表达式
     * table.sort([](const Val& a, const Val& b) {
     *     return getKey(a) < getKey(b);
     * });
     *
     * // 自定义比较器
     * struct CustomCompare {
     *     bool operator()(const Val& a, const Val& b) const {
     *         return a.priority < b.priority;
     *     }
     * };
     * table.sort(CustomCompare());
     * ```
     *
     * 插入排序算法特点：
     * - 简单实现：代码简洁，易于理解和维护
     * - 稳定排序：相等元素的相对位置不变
     * - 原地排序：只需要常数级别的额外空间
     * - 自适应性：对部分有序数据性能接近O(n)
     * - 在线算法：可以在接收数据的同时进行排序
     * - 小数据优势：在小数据集上表现优于复杂排序算法
     */
    template <class StrictWeakOrdering>
    void SortListInsert(StrictWeakOrdering comp);

    /**
     * @brief 链表高效排序（使用默认比较器）
     * @note 算法思路：
     *       1. 收集所有节点索引到std::vector中
     *       2. 使用std::sort进行高效排序（O(n log n)）
     *       3. 根据排序后的索引重新连接链表
     *       4. 保持哈希表结构完整性
     * @note 时间复杂度：O(n log n)，空间复杂度：O(n)
     * @note 优势：
     *       - 利用std::sort的高度优化（内省排序）
     *       - 性能稳定，不受数据分布影响
     *       - 实现简单可靠，维护成本低
     * @note 适用场景：
     *       - 大数据集排序（推荐>50个元素）
     *       - 性能要求较高的场景
     *       - 生产环境需要稳定性能保证
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     * // 插入数据...
     * table.SortListQuick(); // 使用高效排序算法
     * ```
     */
    void SortListQuick()
    {
        SortListQuick(std::less<Val>());
    }

    /**
     * @brief 链表排序方法2（使用自定义比较器）
     * @param comp 比较函数对象
     * @note 算法思路：递归快速排序（Quick Sort for Linked List）
     *       1. 选择基准元素（尾节点）
     *       2. 分区：将小于基准的元素放在左边，大于等于基准的放在右边
     *       3. 递归排序左右两个子链表段
     *       4. 直接重新链接链表指针，保持哈希表完整性
     * @note 时间复杂度：平均O(n log n)，最坏O(n²)，空间复杂度：O(log n)
     * @note 优势：实现符合快速排序经典算法，平均性能优异
     * @note 劣势：最坏情况下退化为O(n²)，不是稳定排序
     *
     * @note 适用场景：一般情况下的高效排序，特别是随机数据
     *
     * 算法特点：
     * - 真正的快速排序实现，基于分区操作
     * - 原地排序，直接修改链表连接
     * - 不需要重建哈希表，保持所有现有数据
     * - 递归实现，算法清晰易懂
     * - 对随机数据有很好的性能表现
     *
     * @note 支持与SortList相同的比较器类型：
     *       - lambda表达式
     *       - 函数指针
     *       - 函数对象
     *       - std::greater<Val>()等标准比较器
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     *
     * // 降序排序
     * table.SortListQuick(std::greater<Val>());
     *
     * // 使用lambda表达式
     * table.SortListQuick([](const Val& a, const Val& b) {
     *     return a.priority > b.priority;
     * });
     *
     * // 复杂排序规则
     * table.SortListQuick([](const Val& a, const Val& b) {
     *     if (a.category != b.category)
     *         return a.category < b.category;
     *     return a.value < b.value;
     * });
     * ```
     */
    template <class StrictWeakOrdering>
    void SortListQuick(StrictWeakOrdering comp);

    /**
     * @brief 链表排序方法3（使用默认比较器）
     * @note 算法思路：链表归并排序（Merge Sort for Linked List）
     *       1. 采用自底向上的归并排序策略
     *       2. 直接在链表上进行原地归并，无需额外空间
     *       3. 不破坏哈希表结构，只重新链接链表指针
     * @note 时间复杂度：O(n log n)，空间复杂度：O(log n)（递归栈）
     * @note 优势：实现简单可靠，性能稳定
     * @note 稳定排序：保持相等元素的相对顺序
     *
     * @note 适用场景：中大型数据集排序，保持哈希表完整性
     *
     * 算法特点：
     * - 递归实现，代码简洁易懂
     * - 原地排序，不需要额外的vector空间
     * - 不需要重建哈希表，保持所有现有数据
     * - 对各种数据分布都有稳定的O(n log n)性能
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     * // 插入数据...
     * table.SortListMerge(); // 使用链表归并排序
     * ```
     */
    void SortListMerge()
    {
        SortListMerge(std::less<Val>());
    }

    /**
     * @brief 链表排序方法3（使用自定义比较器）
     * @param comp 比较函数对象
     * @note 支持与SortList相同的比较器类型：
     *       - lambda表达式
     *       - 函数指针
     *       - 函数对象
     *       - std::greater<Val>()等标准比较器
     *
     * 算法实现细节：
     * 1. 自底向上归并排序：从长度1的子链表开始，逐步合并
     * 2. 每次迭代将子链表长度翻倍：1->2->4->8->...
     * 3. 对于每个长度，遍历整个链表进行两两合并
     * 4. 合并过程直接重新链接节点指针，保持O(1)空间
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     *
     * // 降序排序
     * table.SortListMerge(std::greater<Val>());
     *
     * // 使用lambda表达式
     * table.SortListMerge([](const Val& a, const Val& b) {
     *     return a.priority > b.priority;
     * });
     *
     * // 多级排序
     * table.SortListMerge([](const Val& a, const Val& b) {
     *     if (a.category != b.category)
     *         return a.category < b.category;
     *     return a.timestamp < b.timestamp;
     * });
     * ```
     */
    template <class StrictWeakOrdering>
    void SortListMerge(StrictWeakOrdering comp);

    /**
     * @brief 链表排序方法4（使用默认比较器）
     * @note 算法思路：改进的选择排序（Selection Sort for Linked List）
     *       1. 收集所有节点索引到向量中
     *       2. 使用选择排序对索引进行排序（基于节点值比较）
     *       3. 重新链接链表指针，保持哈希表完整性
     * @note 时间复杂度：O(n²)，空间复杂度：O(n)
     * @note 优势：保持哈希表完整性，实现简单，稳定性能
     * @note 劣势：时间复杂度较高，需要额外内存，不稳定排序
     *
     * @note 适用场景：小数据集排序，保持哈希表完整性
     *
     * 算法特点：
     * - 非递归实现，避免栈溢出
     * - 原地排序，不需要额外的vector空间
     * - 不需要重建哈希表，保持所有现有数据
     * - 稳定性能：对所有数据分布都有相同的O(n²)性能
     * - 简单可靠：逻辑简单，不容易出错
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     * // 插入数据...
     * table.SortListSelect(); // 使用链表选择排序
     * ```
     */
    void SortListSelect()
    {
        SortListSelect(std::less<Val>());
    }

    /**
     * @brief 链表排序方法4（使用自定义比较器）
     * @param comp 比较函数对象
     * @note 支持与其他SortList相同的比较器类型：
     *       - lambda表达式
     *       - 函数指针
     *       - 函数对象
     *       - std::greater<Val>()等标准比较器
     *
     * 算法实现细节：
     * 1. 收集所有节点索引到向量中
     * 2. 使用选择排序对索引进行排序（基于节点值比较）
     * 3. 重新链接链表指针，保持哈希表完整性
     * 4. 不修改节点值，只改变链表链接顺序
     *
     * 性能特点：
     * - 时间复杂度：O(n²) - 稳定的时间复杂度
     * - 空间复杂度：O(n) - 需要额外向量存储索引
     * - 哈希表完整性：保持哈希表结构不被破坏
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     *
     * // 降序排序
     * table.SortListSelect(std::greater<Val>());
     *
     * // 使用lambda表达式
     * table.SortListSelect([](const Val& a, const Val& b) {
     *     return a.priority > b.priority;
     * });
     *
     * // 复杂排序规则
     * table.SortListSelect([](const Val& a, const Val& b) {
     *     if (a.category != b.category)
     *         return a.category < b.category;
     *     return a.score > b.score; // 同类别按分数降序
     * });
     * ```
     */
    template <class StrictWeakOrdering>
    void SortListSelect(StrictWeakOrdering comp);

    // ==================== 高性能优化排序方法（新增） ====================

    /**
     * @brief 高性能归并排序（推荐使用）
     * @note 性能优化版本，预期比原版快 3-8 倍
     * @note 根据数据规模智能选择算法：
     *       - 小数据集(≤32): 插入排序，简单高效
     *       - 中数据集(32-1000): 优化归并排序，平衡性能与复杂度
     *       - 大数据集(>1000): 迭代归并排序，避免递归开销
     * @note 核心优化技术：
     *       1. 缓存节点数组指针，避免重复GetNode()调用
     *       2. 直接数组访问替代间接函数调用
     *       3. 减少分支判断和条件检查
     *       4. 针对不同数据规模使用最优算法
     * @note 与原版兼容：保持相同的稳定性和正确性
     *
     * 使用示例：
     * ```cpp
     * NFShmHashTableWithList<...> table;
     * // 插入数据...
     * table.SortListMergeFast(); // 使用高性能归并排序
     * ```
     */
    void SortListMergeFast()
    {
        SortListMergeFast(std::less<Val>());
    }

    /**
     * @brief 高性能归并排序（自定义比较器）
     * @param comp 比较函数对象
     * @note 支持所有标准比较器类型，性能比原版提升3-8倍
     *
     * 性能优化细节：
     * 1. 减少函数调用：缓存m_astNodes指针，避免GetNode()开销
     * 2. 智能算法选择：根据数据规模自动选择最优排序算法
     * 3. 直接内存访问：使用数组索引替代指针间接访问
     * 4. 减少分支预测失效：优化条件判断逻辑
     *
     * 算法选择策略：
     * - m_size ≤ 32: insertion_sort_fast() - O(n²)但常数小
     * - 32 < m_size ≤ 1000: merge_sort_recursive_fast() - O(n log n)递归
     * - m_size > 1000: merge_sort_iterative_fast() - O(n log n)迭代
     *
     * 使用示例：
     * ```cpp
     * // 降序排序
     * table.SortListMergeFast(std::greater<Val>());
     *
     * // 自定义排序
     * table.SortListMergeFast([](const Val& a, const Val& b) {
     *     return a.priority > b.priority;
     * });
     * ```
     */
    template <class StrictWeakOrdering>
    void SortListMergeFast(StrictWeakOrdering comp);

private:
    /**
     * @brief 插入排序的实现
     * @param comp 比较函数
     * @details 直接在链表上进行插入排序，原地排序算法
     * @note 时间复杂度：O(n²)，空间复杂度：O(1)
     * @note 稳定排序算法，保持相等元素的相对顺序
     */
    template <class StrictWeakOrdering>
    void insertion_sort(StrictWeakOrdering comp);

    /**
     * @brief 递归归并排序主函数
     * @param head 链表头节点索引
     * @param comp 比较函数对象
     * @return 排序后链表的头节点和尾节点索引
     * @note 使用递归分治策略对链表进行归并排序
     */
    template <class StrictWeakOrdering>
    std::pair<int, int> merge_sort_recursive(int head, StrictWeakOrdering comp);

    /**
     * @brief 重新连接链表节点
     * @param nodeIndices 排序后的节点索引数组
     */
    void reconnect_list(const std::vector<int>& nodeIndices);

    /**
     * @brief 分割链表为两半
     * @param head 链表头节点索引
     * @return 第二半链表的头节点索引，第一半的尾节点会被断开连接
     * @note 使用快慢指针法找到链表中点
     */
    int split_list_half(int head);

    /**
     * @brief 合并两个已排序的链表
     * @param left 左链表头节点索引
     * @param right 右链表头节点索引
     * @param comp 比较函数对象
     * @return 合并后链表的头节点和尾节点索引
     * @note 将两个已排序的链表合并为一个排序链表
     */
    template <class StrictWeakOrdering>
    std::pair<int, int> merge_two_lists(int left, int right, StrictWeakOrdering comp);

    /**
     * @brief 选择排序的实现
     * @param comp 比较函数
     * @details 直接在链表上进行选择排序，原地排序算法
     * @note 时间复杂度：O(n²)，空间复杂度：O(1)
     * @note 算法简单可靠，不容易出错
     */
    template <class StrictWeakOrdering>
    void selection_sort(StrictWeakOrdering comp);

    // ==================== 高性能优化辅助方法声明（新增） ====================

    /**
     * @brief 快速插入排序（针对小数据集优化）
     * @param nodes 节点数组指针
     * @param comp 比较函数对象
     * @note 避免GetNode调用，直接使用数组访问
     */
    template <class StrictWeakOrdering>
    void insertion_sort_fast(Node* nodes, StrictWeakOrdering comp);

    /**
     * @brief 快速递归归并排序
     * @param head 链表头节点索引
     * @param nodes 节点数组指针
     * @param comp 比较函数对象
     * @return 排序后链表的头尾节点索引
     * @note 缓存节点数组指针，减少函数调用开销
     */
    template <class StrictWeakOrdering>
    std::pair<int, int> merge_sort_recursive_fast(int head, Node* nodes, StrictWeakOrdering comp);

    /**
     * @brief 快速链表分割
     * @param head 链表头节点索引
     * @param nodes 节点数组指针
     * @return 第二半链表的头节点索引
     * @note 直接数组访问，避免GetNode调用
     */
    int split_list_fast(int head, Node* nodes);

    /**
     * @brief 快速合并两个已排序链表
     * @param left 左链表头
     * @param right 右链表头
     * @param nodes 节点数组指针
     * @param comp 比较函数对象
     * @return 合并后链表的头尾节点索引
     * @note 优化的合并算法，减少指针操作
     */
    template <class StrictWeakOrdering>
    std::pair<int, int> merge_two_lists_fast(int left, int right, Node* nodes, StrictWeakOrdering comp);

    /**
     * @brief 迭代归并排序（大数据集优化）
     * @param nodes 节点数组指针
     * @param comp 比较函数对象
     * @note 使用标准库排序+链表重建，对大数据集最优
     */
    template <class StrictWeakOrdering>
    void merge_sort_iterative_fast(Node* nodes, StrictWeakOrdering comp);

    /**
     * @brief 快速重建链表
     * @param sortedIndices 排序后的节点索引
     * @param nodes 节点数组指针
     * @note 批量重建链表连接，提高效率
     */
    void rebuild_list_fast(const std::vector<int>& sortedIndices, Node* nodes);

    /**
     * @brief 辅助函数：快速找到链表尾部
     * @param head 链表头
     * @param nodes 节点数组指针
     * @return 尾节点索引
     */
    int find_tail_fast(int head, Node* nodes);

    /**
     * @brief 辅助函数：将节点添加到结果链表
     * @param nodeIdx 要添加的节点
     * @param resultHead 结果链表头（引用）
     * @param resultTail 结果链表尾（引用）
     * @param nodes 节点数组指针
     */
    void append_to_result_fast(int nodeIdx, int& resultHead, int& resultTail, Node* nodes);

    /**
     * @brief 辅助函数：从链表中快速移除节点
     * @param nodeIdx 要移除的节点
     * @param nodes 节点数组指针
     */
    void remove_from_list_fast(int nodeIdx, Node* nodes);

    /**
     * @brief 辅助函数：在指定位置前快速插入节点
     * @param nodeIdx 要插入的节点
     * @param beforeIdx 插入位置（在此节点前）
     * @param nodes 节点数组指针
     */
    void insert_before_fast(int nodeIdx, int beforeIdx, Node* nodes);

private:
    /**
     * @brief 将节点添加到链表尾部
     * @param pNode 要添加的节点
     * @note 用于新插入的节点
     */
    void AddToListTail(Node* pNode);

    /**
     * @brief 将节点添加到链表尾部
     * @param pNode 要添加的节点
     * @note 用于新插入的节点
     */
    void AddToListHead(Node* pNode);

    /**
     * @brief 从链表中移除节点
     * @param pNode 要移除的节点
     * @note 用于删除节点时
     */
    void RemoveFromList(Node* pNode);

    /**
     * @brief 将节点移动到链表尾部
     * @param pNode 要移动的节点
     * @note 用于LRU访问时
     */
    void MoveToListTail(Node* pNode);

    /**
     * @brief 将节点移动到链表尾部
     * @param pNode 要移动的节点
     * @note 用于LRU访问时
     */
    void MoveToListHead(Node* pNode);

    /**
     * @brief 初始化链表管理变量
     * @note 在InitializeBuckets中调用
     */
    void InitializeList();

    /**
     * @brief 将节点移动到链表尾部
     * @param pNode 要移动的节点
     * @note 用于LRU访问时
     */
    void MoveToListNodeFront(Node* pSelf, Node* pNode);
    void MoveToListNodeBack(Node* pSelf, Node* pNode);

    // ==================== 有序链表二分搜索辅助函数（新增） ====================
public:
    /**
     * @brief 在有序链表中使用二分搜索找到插入位置
     * @param pSelfNode
     * @param comp 比较函数
     * @return true表示找到合适的插入位置，false表示出错
     * @note 时间复杂度：O(log n)
     */
    template <class Compare>
    Node* BinarySearchInsertPosition(Node* pSelfNode, Compare comp);

    template <class Compare>
    Node* LineSearchInsertPosition(Node* pSelfNode, Compare comp);

private:
    /**
     * @brief 将有序链表转换为索引数组（用于二分搜索）
     * @param nodeIndices 输出的节点索引数组
     * @param pSelfNode
     * @note 时间复杂度：O(n)，只在需要时调用
     */
    void CollectSortedNodeIndices(std::vector<int>& nodeIndices, Node* pSelfNode);

    /**
     * @brief 使用std::lower_bound/upper_bound查找插入位置
     * @param nodeIndices 排序的节点索引数组
     * @param pTargetNode
     * @param comp 比较函数
     * @param isAscending 是否升序
     * @return 目标插入位置的索引
     * @note 使用标准库算法，性能更优且代码更简洁
     */
    template <class Compare>
    Node* FindSortedInsertPosition(const std::vector<int>& nodeIndices, Node* pTargetNode, Compare comp);

    // ==================== 快速查找优化接口（新增） ====================
public:
    /**
     * @brief 快速查找插入位置（使用SortListMergeFast技术优化）
     * @param pSelfNode 要移动的节点
     * @param comp 比较函数
     * @return 插入位置的节点，nullptr表示插入到尾部
     * @note 性能优化版本，减少内存分配和间接访问
     * @note 时间复杂度：O(log n) 最优情况，O(n) 最坏情况
     */
    template <class Compare>
    Node* FastSearchInsertPosition(Node* pSelfNode, Compare comp);

private:
    /**
     * @brief 直接在链表上进行二分查找（无需额外内存分配）
     * @param nodes 节点数组指针（直接访问，避免GetNode开销）
     * @param pTargetNode 目标节点
     * @param comp 比较函数
     * @return 插入位置的节点索引
     * @note 使用快慢指针技术，类似SortListMergeFast的分割策略
     */
    template <class Compare>
    int fast_binary_search_on_list(Node* nodes, Node* pTargetNode, Compare comp);

    template <class Compare>
    int fast_binary_search_on_list_optimized(Node* nodes, Node* pTargetNode, Compare comp);

public:
    /**
     * @brief 自适应查找策略：根据数据规模选择最优算法
     * @param pSelfNode 要移动的节点
     * @param comp 比较函数
     * @return 插入位置的节点
     * @note 小数据集使用线性搜索，大数据集使用优化的二分查找
     */
    template <class Compare>
    Node* AdaptiveSearchInsertPosition(Node* pSelfNode, Compare comp);
};

// ==================== 静态成员定义 ====================

template <class Val, class Key, int MAX_SIZE, class Hf, class Ex, class Eq>
Val NFShmHashTableWithList<Val, Key, MAX_SIZE, Hf, Ex, Eq>::m_staticError = Val();

// ==================== 迭代器实现 ====================

/**
 * @brief 迭代器前置递增操作符实现
 * @note 移动到下一个有效元素，跨桶遍历
 */
template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>& NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>::operator++()
{
    const Node* old = m_curNode;
    if (old)
    {
        m_curNode = m_hashTable->GetNode(m_curNode->m_next);
        if (!m_curNode)
        {
            size_type bucket = m_hashTable->BktNum(old->m_value);
            while (!m_curNode && ++bucket < MAX_SIZE)
                m_curNode = m_hashTable->GetNode(m_hashTable->m_bucketsFirstIdx[bucket]);
        }
    }
    return *this;
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk> NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>::operator++(int)
{
    iterator tmp = *this;
    ++*this;
    return tmp;
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>& NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>::operator++()
{
    const Node* old = m_curNode;
    if (old)
    {
        m_curNode = m_hashTable->GetNode(m_curNode->m_next);
        if (!m_curNode)
        {
            size_type bucket = m_hashTable->BktNum(old->m_value);
            while (!m_curNode && ++bucket < MAX_SIZE)
                m_curNode = m_hashTable->GetNode(m_hashTable->m_bucketsFirstIdx[bucket]);
        }
    }
    return *this;
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk> NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>::operator++(int)
{
    const_iterator tmp = *this;
    ++*this;
    return tmp;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::CreateNode()
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, nullptr, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(m_firstFreeIdx >= 0 && m_firstFreeIdx < MAX_SIZE, nullptr, "Invalid free index %d, valid range [0, %d), TRACE_STACK:%s", m_firstFreeIdx, MAX_SIZE, TRACE_STACK());
    auto pBuckets = GetBuckets();

    int iNowAssignIdx = m_firstFreeIdx;
    m_firstFreeIdx = pBuckets[m_firstFreeIdx].m_next;
    ++m_size;
    return &pBuckets[iNowAssignIdx];
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::RecycleNode(Node* p)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(p != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(p->m_valid, "Node is already invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(p->m_self >= 0 && p->m_self < MAX_SIZE, "Node self index out of range: %zu, TRACE_STACK:%s", p->m_self, TRACE_STACK());
    CHECK_EXPR_RE_VOID(m_size > 0, "Size is already 0, cannot recycle node, TRACE_STACK:%s", TRACE_STACK());

    p->m_valid = false;
    p->m_next = m_firstFreeIdx;
    m_firstFreeIdx = p->m_self;
    --m_size;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::NFShmHashTableWithList()
{
    m_hash = HashFcn();
    m_equals = EqualKey();
    m_getKey = ExtractKey();

    if (SHM_CREATE_MODE)
    {
        CreateInit();
    }
    else
    {
        ResumeInit();
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::NFShmHashTableWithList(const NFShmHashTableWithList& ht)
{
    m_hash = HashFcn();
    m_equals = EqualKey();
    m_getKey = ExtractKey();
    CreateInit();
    CopyFrom(ht);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>& NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::operator=(const NFShmHashTableWithList& ht)
{
    if (&ht != this)
    {
        CopyFrom(ht);
    }
    return *this;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::~NFShmHashTableWithList()
{
    clear();
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::CreateInit()
{
    InitializeBuckets();
    InitializeList(); // 新增：初始化链表管理变量
    m_enableLRU = false; // 新增：默认禁用LRU功能
    m_enableInsertHead = false; // 新增：默认插入到链表尾部
    m_init = EN_NF_SHM_STL_INIT_OK;
    return 0;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::ResumeInit()
{
    if (m_init == EN_NF_SHM_STL_INIT_OK)
    {
        auto pNode = GetBuckets();
        // 对于非平凡构造的类型，恢复时需要调用构造函数
        if (!std::stl_is_trivially_default_constructible<Val>::value)
        {
            for (size_t i = 0; i < MAX_SIZE; i++)
            {
                if (pNode[i].m_valid)
                {
                    std::_Construct(&pNode[i].m_value);
                }
            }
        }
    }
    return 0;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Init()
{
    new(this) NFShmHashTableWithList();
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    return m_size;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::max_size() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, MAX_SIZE, "not init, TRACE_STACK:%s", TRACE_STACK());
    return MAX_SIZE;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
bool NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::empty() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, true, "not init, TRACE_STACK:%s", TRACE_STACK());
    return m_size == 0;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
bool NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::full() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, false, "not init, TRACE_STACK:%s", TRACE_STACK());
    return m_size == MAX_SIZE;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
size_t NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::left_size() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    return m_size >= MAX_SIZE ? 0 : MAX_SIZE - m_size;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::GetNode(int idx)
{
    if (idx >= 0 && idx < MAX_SIZE)
    {
        auto pBuckets = GetBuckets();
        auto pNode = &pBuckets[idx];
        CHECK_EXPR(pNode->m_self == idx, nullptr, "Node self index mismatch: expected %d, got %zu, TRACE_STACK:%s", idx, pNode->m_self, TRACE_STACK());
        if (pNode->m_valid)
        {
            return pNode;
        }
    }
    return nullptr;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
const typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::GetNode(int idx) const
{
    if (idx >= 0 && idx < MAX_SIZE)
    {
        auto pBuckets = GetBuckets();
        auto pNode = &pBuckets[idx];
        CHECK_EXPR(pNode->m_self == idx, nullptr, "Node self index mismatch: expected %d, got %zu, TRACE_STACK:%s", idx, pNode->m_self, TRACE_STACK());
        if (pNode->m_valid)
        {
            return pNode;
        }
    }
    return nullptr;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::get_iterator(int idx)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(idx >= 0 && idx < MAX_SIZE, iterator(nullptr, this), "Index out of range: %d, TRACE_STACK:%s", idx, TRACE_STACK());
    return iterator(GetNode(idx), this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::get_iterator(int idx) const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, const_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(idx >= 0 && idx < MAX_SIZE, const_iterator(nullptr, this), "Index out of range: %d, TRACE_STACK:%s", idx, TRACE_STACK());
    return const_iterator(GetNode(idx), this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::swap(NFShmHashTableWithList& other) noexcept
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, , "this not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(other.m_init == EN_NF_SHM_STL_INIT_OK, , "other not init, TRACE_STACK:%s", TRACE_STACK());

    if (this != &other)
    {
        NFShmHashTableWithList temp(*this);
        CopyFrom(other);
        other.CopyFrom(temp);
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::begin()
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    for (size_type n = 0; n < MAX_SIZE; ++n)
        if (m_bucketsFirstIdx[n] != INVALID_ID)
            return iterator(GetNode(m_bucketsFirstIdx[n]), this);
    return end();
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::end()
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return iterator(nullptr, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::begin() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, const_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    for (size_type n = 0; n < MAX_SIZE; ++n)
        if (m_bucketsFirstIdx[n] != INVALID_ID)
            return const_iterator(GetNode(m_bucketsFirstIdx[n]), this);
    return end();
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::end() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, const_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return const_iterator(nullptr, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::bucket_count() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    return MAX_SIZE;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::max_bucket_count() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    return MAX_SIZE;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::elems_in_bucket(size_type bucket) const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(bucket < MAX_SIZE, 0, "bucket index out of range: %lu >= %d, TRACE_STACK:%s", bucket, MAX_SIZE, TRACE_STACK());

    size_type result = 0;
    int curIndex = (int)bucket;
    int firstIdx = m_bucketsFirstIdx[curIndex];

    if (firstIdx >= 0 && firstIdx < MAX_SIZE)
    {
        auto pNode = GetNode(firstIdx);
        size_type maxIterations = m_size + 1; // 防止无限循环
        size_type iterations = 0;

        while (pNode && iterations < maxIterations)
        {
            result++;
            iterations++;
            pNode = GetNode(pNode->m_next);
        }

        CHECK_EXPR(iterations < maxIterations, result, "Possible infinite loop detected in bucket %lu, TRACE_STACK:%s", bucket, TRACE_STACK());
    }
    return result;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
std::pair<typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator, bool> NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_unique(const value_type& obj)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, (std::pair<iterator, bool>(iterator(nullptr, this), false)), "not init, TRACE_STACK:%s", TRACE_STACK());
    return insert_unique_noresize(obj);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_equal(const value_type& obj)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return insert_equal_noresize(obj);
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
std::forward_iterator_tag iterator_category(const NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>&)
{
    return std::forward_iterator_tag();
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
Val* value_type(const NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>&)
{
    return nullptr;
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, ExK, Eqk>::difference_type* distance_type(const NFShmHashTableWithListIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>&)
{
    return nullptr;
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
std::forward_iterator_tag iterator_category(const NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>&)
{
    return std::forward_iterator_tag();
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
Val* value_type(const NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>&)
{
    return nullptr;
}

template <class Val, class Key, int MAX_SIZE, class HF, class ExK, class Eqk>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, ExK, Eqk>::difference_type* distance_type(const NFShmHashTableWithListConstIterator<Val, Key, MAX_SIZE, HF, ExK, Eqk>&)
{
    return nullptr;
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
bool operator==(const NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>& ht1, const NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>& ht2)
{
    if (ht1.size() != ht2.size())
        return false;

    typedef typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::Node Node;
    for (int n = 0; n < MAX_SIZE; ++n)
    {
        const Node* cur1 = ht1.GetNode(ht1.m_bucketsFirstIdx[n]);
        const Node* cur2 = ht2.GetNode(ht2.m_bucketsFirstIdx[n]);

        while (cur1 && cur2)
        {
            if (!(cur1->m_value == cur2->m_value))
                return false;
            cur1 = ht1.GetNode(cur1->m_next);
            cur2 = ht2.GetNode(cur2->m_next);
        }

        if (cur1 || cur2) // 链表长度不同
            return false;
    }
    return true;
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
bool operator!=(const NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>& ht1, const NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>& ht2)
{
    return !(ht1 == ht2);
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
void swap(NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>& ht1, NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>& ht2) noexcept
{
    ht1.swap(ht2);
}


template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
std::pair<typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator, bool> NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::insert_unique_noresize(const value_type& obj)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, (std::pair<iterator, bool>(iterator(nullptr, this), false)), "not init, TRACE_STACK:%s", TRACE_STACK());
    const size_type n = BktNum(obj);
    CHECK_EXPR(n < MAX_SIZE, (std::pair<iterator, bool>(end(), false)), "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());

    int iFirstIndex = m_bucketsFirstIdx[n];
    for (Node* cur = GetNode(iFirstIndex); cur; cur = GetNode(cur->m_next))
    {
        if (m_equals(m_getKey(cur->m_value), m_getKey(obj)))
        {
            return std::pair<iterator, bool>(iterator(cur, this), false);
        }
    }

    Node* tmp = NewNode(obj);
    if (tmp == nullptr)
    {
        return std::pair<iterator, bool>(end(), false);
    }

    tmp->m_next = iFirstIndex;
    m_bucketsFirstIdx[n] = tmp->m_self;
    return std::pair<iterator, bool>(iterator(tmp, this), true);
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::insert_equal_noresize(const value_type& obj)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());

    //已经没有可用的节点了
    const size_type n = BktNum(obj);
    CHECK_EXPR(n < MAX_SIZE, end(), "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());

    int iFirstIndex = m_bucketsFirstIdx[n];

    for (Node* cur = GetNode(iFirstIndex); cur; cur = GetNode(cur->m_next))
    {
        if (m_equals(m_getKey(cur->m_value), m_getKey(obj)))
        {
            Node* tmp = NewNode(obj);
            if (tmp == nullptr)
            {
                return end();
            }
            tmp->m_next = cur->m_next;
            cur->m_next = tmp->m_self;
            return iterator(tmp, this);
        }
    }

    Node* tmp = NewNode(obj);
    if (tmp == nullptr)
    {
        return end();
    }

    tmp->m_next = iFirstIndex;
    m_bucketsFirstIdx[n] = tmp->m_self;
    return iterator(tmp, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class InputIterator>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_unique(InputIterator f, InputIterator l)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    insert_unique(f, l, typename std::iterator_traits<InputIterator>::iterator_category());
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class InputIterator>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_equal(InputIterator f, InputIterator l)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    insert_equal(f, l, typename std::iterator_traits<InputIterator>::iterator_category());
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class InputIterator>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_unique(InputIterator f, InputIterator l, std::input_iterator_tag)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    for (; f != l; ++f)
        insert_unique(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class InputIterator>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_equal(InputIterator f, InputIterator l, std::input_iterator_tag)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    for (; f != l; ++f)
        insert_equal(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class ForwardIterator>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_unique(ForwardIterator f, ForwardIterator l, std::forward_iterator_tag)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = std::distance(f, l);
    size_type left = left_size();
    if (left < n)
    {
        LOG_WARN(0, -1, "NFShmHashTableWithList does not have enough space: (left:%lu, insert:%lu), only insert left:%lu, TRACE_STACK:%s", left, n, left, TRACE_STACK());
        n = left;
    }
    for (; n > 0; --n, ++f)
        insert_unique_noresize(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class ForwardIterator>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_equal(ForwardIterator f, ForwardIterator l, std::forward_iterator_tag)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = std::distance(f, l);
    size_type left = left_size();
    if (left < n)
    {
        LOG_WARN(0, -1, "NFShmHashTableWithList does not have enough space: (left:%lu, insert:%lu), only insert left:%lu, TRACE_STACK:%s", left, n, left, TRACE_STACK());
        n = left;
    }
    for (; n > 0; --n, ++f)
        insert_equal_noresize(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_unique(const value_type* f, const value_type* l)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = l - f;
    size_type left = left_size();
    if (left < n)
    {
        LOG_WARN(0, -1, "NFShmHashTableWithList does not have enough space: (left:%lu, insert:%lu), only insert left:%lu, TRACE_STACK:%s", left, n, left, TRACE_STACK());
        n = left;
    }
    for (; n > 0; --n, ++f)
        insert_unique_noresize(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_equal(const value_type* f, const value_type* l)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = l - f;
    size_type left = left_size();
    if (left < n)
    {
        LOG_WARN(0, -1, "NFShmHashTableWithList does not have enough space: (left:%lu, insert:%lu), only insert left:%lu, TRACE_STACK:%s", left, n, left, TRACE_STACK());
        n = left;
    }
    for (; n > 0; --n, ++f)
        insert_equal_noresize(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_unique(const_iterator f, const_iterator l)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = std::distance(f, l);
    size_type left = left_size();
    if (left < n)
    {
        LOG_WARN(0, -1, "NFShmHashTableWithList does not have enough space: (left:%lu, insert:%lu), only insert left:%lu, TRACE_STACK:%s", left, n, left, TRACE_STACK());
        n = left;
    }
    for (; n > 0; --n, ++f)
        insert_unique_noresize(*f);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_equal(const_iterator f, const_iterator l)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = std::distance(f, l);
    size_type left = left_size();
    if (left < n)
    {
        LOG_WARN(0, -1, "NFShmHashTableWithList does not have enough space: (left:%lu, insert:%lu), only insert left:%lu, TRACE_STACK:%s", left, n, left, TRACE_STACK());
        n = left;
    }
    for (; n > 0; --n, ++f)
        insert_equal_noresize(*f);
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::reference NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::find_or_insert(const value_type& obj)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, m_staticError, "not init, TRACE_STACK:%s", TRACE_STACK());
    const size_type n = BktNum(obj);
    CHECK_EXPR(n < MAX_SIZE, m_staticError, "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());

    int iFirstIndex = m_bucketsFirstIdx[n];
    for (Node* cur = GetNode(iFirstIndex); cur; cur = GetNode(cur->m_next))
    {
        if (m_equals(m_getKey(cur->m_value), m_getKey(obj)))
        {
            return cur->m_value;
        }
    }

    Node* tmp = NewNode(obj);
    CHECK_EXPR(tmp != nullptr, m_staticError, "Failed to create new node, TRACE_STACK:%s", TRACE_STACK());

    tmp->m_next = m_bucketsFirstIdx[n];
    m_bucketsFirstIdx[n] = tmp->m_self;
    return tmp->m_value;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::find(const key_type& key)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = BktNumKey(key);
    CHECK_EXPR(n < MAX_SIZE, end(), "n:%lu >= MAX_SIZE:%lu TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());
    int iFirstIndex = m_bucketsFirstIdx[n];

    Node* first;
    for (first = GetNode(iFirstIndex); first && !m_equals(m_getKey(first->m_value), key); first = GetNode(first->m_next))
    {
    }

    // 新增：如果启用LRU功能且找到节点，将节点移动到链表尾部
    if (first && m_enableLRU)
    {
        if (m_enableInsertHead)
        {
            MoveToListHead(first);
        }
        else
        {
            MoveToListTail(first);
        }
    }

    return iterator(first, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::find(const key_type& key) const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type n = BktNumKey(key);
    CHECK_EXPR(n < MAX_SIZE, end(), "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());
    int iFirstIndex = m_bucketsFirstIdx[n];

    const Node* first;
    for (first = GetNode(iFirstIndex); first && !m_equals(m_getKey(first->m_value), key); first = GetNode(first->m_next))
    {
    }

    // 新增：如果启用LRU功能且找到节点，将节点移动到链表尾部
    if (first && m_enableLRU)
    {
        if (m_enableInsertHead)
        {
            (const_cast<NFShmHashTableWithList*>(this))->MoveToListHead(const_cast<Node*>(first));
        }
        else
        {
            (const_cast<NFShmHashTableWithList*>(this))->MoveToListTail(const_cast<Node*>(first));
        }
    }

    return const_iterator(first, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::count(const key_type& key) const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    const size_type n = BktNumKey(key);
    size_type result = 0;
    CHECK_EXPR(n < MAX_SIZE, 0, "n:%lu >= MAX_SIZE:%lu TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());
    int iFirstIndex = m_bucketsFirstIdx[n];

    for (const Node* cur = GetNode(iFirstIndex); cur; cur = GetNode(cur->m_next))
    {
        if (m_equals(m_getKey(cur->m_value), key))
        {
            ++result;

            // 新增：如果启用LRU功能且找到节点，将最后一个匹配的节点移动到链表尾部
            if (m_enableLRU)
            {
                if (m_enableInsertHead)
                {
                    (const_cast<NFShmHashTableWithList*>(this))->MoveToListHead(const_cast<Node*>(cur));
                }
                else
                {
                    (const_cast<NFShmHashTableWithList*>(this))->MoveToListTail(const_cast<Node*>(cur));
                }
            }
        }
    }

    return result;
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
std::pair<typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator, typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator> NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::equal_range(const key_type& key)
{
    typedef std::pair<iterator, iterator> pii;
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, pii(end(), end()), "not init, TRACE_STACK:%s", TRACE_STACK());
    const size_type n = BktNumKey(key);
    CHECK_EXPR(n < MAX_SIZE, (pii(end(), end())), "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());

    int iFirstIndex = m_bucketsFirstIdx[n];
    for (Node* first = GetNode(iFirstIndex); first; first = GetNode(first->m_next))
    {
        if (m_equals(m_getKey(first->m_value), key))
        {
            // 新增：如果启用LRU功能，将找到的第一个匹配节点移动到链表尾部
            if (m_enableLRU)
            {
                if (m_enableInsertHead)
                {
                    MoveToListHead(first);
                }
                else
                {
                    MoveToListTail(first);
                }
            }

            for (Node* cur = GetNode(first->m_next); cur; cur = GetNode(cur->m_next))
            {
                if (!m_equals(m_getKey(cur->m_value), key))
                {
                    return pii(iterator(first, this), iterator(cur, this));
                }

                // 新增：如果启用LRU功能，将找到的每个匹配节点移动到链表尾部
                if (m_enableLRU)
                {
                    if (m_enableInsertHead)
                    {
                        MoveToListHead(cur);
                    }
                    else
                    {
                        MoveToListTail(cur);
                    }
                }
            }
            for (size_type m = n + 1; m < MAX_SIZE; ++m)
            {
                if (m_bucketsFirstIdx[m] != INVALID_ID)
                {
                    return pii(iterator(first, this), iterator(GetNode(m_bucketsFirstIdx[m]), this));
                }
            }
            return pii(iterator(first, this), end());
        }
    }
    return pii(end(), end());
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
std::pair<typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::const_iterator, typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::const_iterator> NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::equal_range(const key_type& key) const
{
    typedef std::pair<const_iterator, const_iterator> pii;
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, (pii(end(), end())), "not init, TRACE_STACK:%s", TRACE_STACK());
    const size_type n = BktNumKey(key);
    CHECK_EXPR(n < MAX_SIZE, (pii(end(), end())), "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());

    int iFirstIndex = m_bucketsFirstIdx[n];
    for (const Node* first = GetNode(iFirstIndex); first; first = GetNode(first->m_next))
    {
        if (m_equals(m_getKey(first->m_value), key))
        {
            // 新增：如果启用LRU功能，将找到的第一个匹配节点移动到链表尾部
            if (m_enableLRU)
            {
                if (m_enableInsertHead)
                {
                    (const_cast<NFShmHashTableWithList*>(this))->MoveToListHead(const_cast<Node*>(first));
                }
                else
                {
                    (const_cast<NFShmHashTableWithList*>(this))->MoveToListTail(const_cast<Node*>(first));
                }
            }

            for (const Node* cur = GetNode(first->m_next); cur; cur = GetNode(cur->m_next))
            {
                if (!m_equals(m_getKey(cur->m_value), key))
                {
                    return pii(const_iterator(first, this), const_iterator(cur, this));
                }

                // 新增：如果启用LRU功能，将找到的每个匹配节点移动到链表尾部
                if (m_enableLRU)
                {
                    if (m_enableInsertHead)
                    {
                        (const_cast<NFShmHashTableWithList*>(this))->MoveToListHead(const_cast<Node*>(cur));
                    }
                    else
                    {
                        (const_cast<NFShmHashTableWithList*>(this))->MoveToListTail(const_cast<Node*>(cur));
                    }
                }
            }
            for (size_type m = n + 1; m < MAX_SIZE; ++m)
            {
                if (m_bucketsFirstIdx[m] != INVALID_ID)
                {
                    return pii(const_iterator(first, this), const_iterator(GetNode(m_bucketsFirstIdx[m]), this));
                }
            }
            return pii(const_iterator(first, this), end());
        }
    }
    return pii(end(), end());
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(const key_type& key)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, 0, "not init, TRACE_STACK:%s", TRACE_STACK());
    const size_type n = BktNumKey(key);
    CHECK_EXPR(n < MAX_SIZE, 0, "bucket index n:%lu >= MAX_SIZE:%lu, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());
    int iFirstIndex = m_bucketsFirstIdx[n];
    size_type erased = 0;

    Node* first = GetNode(iFirstIndex);
    if (first)
    {
        Node* cur = first;
        Node* next = GetNode(cur->m_next);
        while (next)
        {
            if (m_equals(m_getKey(next->m_value), key))
            {
                cur->m_next = next->m_next;
                DeleteNode(next);
                next = GetNode(cur->m_next);
                ++erased;
            }
            else
            {
                cur = next;
                next = GetNode(cur->m_next);
            }
        }
        if (m_equals(m_getKey(first->m_value), key))
        {
            m_bucketsFirstIdx[n] = first->m_next;
            DeleteNode(first);
            ++erased;
        }
    }
    return erased;
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(iterator it)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(it.m_curNode != nullptr, end(), "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(it.m_curNode->m_valid, end(), "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    Node* nodeToDelete = it.m_curNode;

    // 先获取下一个迭代器，再删除当前节点
    iterator nextIter = it;
    ++nextIter; // 利用iterator++操作获取下一个有效迭代器

    // 现在安全地删除节点
    const size_type bucketIndex = BktNum(nodeToDelete->m_value);
    CHECK_EXPR(bucketIndex < MAX_SIZE, end(), "Bucket index out of range: %zu, TRACE_STACK:%s", bucketIndex, TRACE_STACK());

    int& bucketHead = m_bucketsFirstIdx[bucketIndex];
    Node* currentNode = GetNode(bucketHead);

    if (currentNode == nodeToDelete)
    {
        // 删除链表头节点
        bucketHead = nodeToDelete->m_next;
        DeleteNode(nodeToDelete);
        return nextIter;
    }
    else
    {
        // 删除链表中间或尾部节点
        while (currentNode && currentNode->m_next != INVALID_ID)
        {
            Node* nextInChain = GetNode(currentNode->m_next);
            if (nextInChain == nodeToDelete)
            {
                currentNode->m_next = nodeToDelete->m_next;
                DeleteNode(nodeToDelete);
                return nextIter;
            }
            currentNode = nextInChain;
        }

        // 如果没有找到要删除的节点，这是一个错误情况
        CHECK_EXPR(false, end(), "Node to delete not found in bucket chain, TRACE_STACK:%s", TRACE_STACK());
        return end();
    }
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(list_iterator it)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, list_end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(it.m_curNode != nullptr, list_end(), "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(it.m_curNode->m_valid, list_end(), "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    Node* nodeToDelete = it.m_curNode;

    // 先获取下一个迭代器，再删除当前节点
    list_iterator nextIter = it;
    ++nextIter; // 利用iterator++操作获取下一个有效迭代器

    // 现在安全地删除节点
    const size_type bucketIndex = BktNum(nodeToDelete->m_value);
    CHECK_EXPR(bucketIndex < MAX_SIZE, list_end(), "Bucket index out of range: %zu, TRACE_STACK:%s", bucketIndex, TRACE_STACK());

    int& bucketHead = m_bucketsFirstIdx[bucketIndex];
    Node* currentNode = GetNode(bucketHead);

    if (currentNode == nodeToDelete)
    {
        // 删除链表头节点
        bucketHead = nodeToDelete->m_next;
        DeleteNode(nodeToDelete);
        return nextIter;
    }
    else
    {
        // 删除链表中间或尾部节点
        while (currentNode && currentNode->m_next != INVALID_ID)
        {
            Node* nextInChain = GetNode(currentNode->m_next);
            if (nextInChain == nodeToDelete)
            {
                currentNode->m_next = nodeToDelete->m_next;
                DeleteNode(nodeToDelete);
                return nextIter;
            }
            currentNode = nextInChain;
        }

        // 如果没有找到要删除的节点，这是一个错误情况
        CHECK_EXPR(false, list_end(), "Node to delete not found in bucket chain, TRACE_STACK:%s", TRACE_STACK());
        return list_end();
    }
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(iterator first, iterator last)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    size_type fBucket = first.m_curNode ? BktNum(first.m_curNode->m_value) : MAX_SIZE;
    size_type lBucket = last.m_curNode ? BktNum(last.m_curNode->m_value) : MAX_SIZE;

    if (first.m_curNode == last.m_curNode)
    {
        return last;
    }
    else if (fBucket == lBucket)
    {
        EraseBucket(fBucket, first.m_curNode, last.m_curNode);
        return last;
    }
    else
    {
        EraseBucket(fBucket, first.m_curNode, nullptr);
        for (size_type n = fBucket + 1; n < lBucket; ++n)
            EraseBucket(n, nullptr);
        if (lBucket != MAX_SIZE)
            EraseBucket(lBucket, last.m_curNode);
    }
    return last;
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(const_iterator first, const_iterator last)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    return erase(iterator(const_cast<Node*>(first.m_curNode), const_cast<NFShmHashTableWithList*>(first.m_hashTable)), iterator(const_cast<Node*>(last.m_curNode), const_cast<NFShmHashTableWithList*>(last.m_hashTable)));
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(const_iterator it)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    return erase(iterator(const_cast<Node*>(it.m_curNode), const_cast<NFShmHashTableWithList*>(it.m_hashTable)));
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::erase(const_list_iterator it)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, list_end(), "not init, TRACE_STACK:%s", TRACE_STACK());
    return erase(list_iterator(const_cast<Node*>(it.m_curNode), const_cast<NFShmHashTableWithList*>(it.m_hashTable)));
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::resize(size_type)
{
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::EraseBucket(const size_type n, Node* first, Node* last)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(n < MAX_SIZE, "n:%zu >= MAX_SIZE:%d, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());
    Node* cur = GetNode(m_bucketsFirstIdx[n]);
    CHECK_EXPR_RE_VOID(cur, "TRACE_STACK:%s", TRACE_STACK());
    if (cur == first)
        EraseBucket(n, last);
    else
    {
        Node* next;
        for (next = GetNode(cur->m_next); next != first; cur = next, next = GetNode(cur->m_next))
        {
        }
        while (next != last)
        {
            cur->m_next = next->m_next;
            DeleteNode(next);
            next = GetNode(cur->m_next);
        }
    }
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::EraseBucket(const size_type n, Node* last)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(n < MAX_SIZE, "n:%zu >= MAX_SIZE:%d, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());
    Node* cur = GetNode(m_bucketsFirstIdx[n]);
    if (!cur)
        return;

    while (cur != last)
    {
        if (cur)
        {
            Node* next = GetNode(cur->m_next);
            DeleteNode(cur);
            cur = next;
        }
        else
        {
            LOG_ERR(0, -1, "error, TRACE_STACK:%s", TRACE_STACK());
            break;
        }

        m_bucketsFirstIdx[n] = cur ? cur->m_self : INVALID_ID;
    }
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::clear()
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());

    for (int i = 0; i < MAX_SIZE; i++)
    {
        auto pNode = GetNode(m_bucketsFirstIdx[i]);
        while (pNode)
        {
            int next = pNode->m_next;
            DeleteNode(pNode);
            pNode = GetNode(next);
        }
        m_bucketsFirstIdx[i] = INVALID_ID;
    }

    InitializeBuckets();
    InitializeList(); // 新增：重置链表状态
}


template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::print_structure() const
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());

    printf("\n=== NFShmHashTableWithList Structure ===\n");
    printf("Size: %zu, Max Size: %d, First Free Index: %d\n", m_size, MAX_SIZE, m_firstFreeIdx);
    printf("LRU enabled: %s, List head: %d, List tail: %d\n", m_enableLRU ? "Yes" : "No", m_listHead, m_listTail);

    // 验证链表完整性
    bool listIntegrityOK = ValidateListIntegrity();
    printf("List integrity: %s\n", listIntegrityOK ? "OK" : "FAILED");

    printf("=====================================\n");

    size_type totalNodes = 0;
    size_type emptyBuckets = 0;

    for (size_type i = 0; i < MAX_SIZE; ++i)
    {
        int firstIdx = m_bucketsFirstIdx[i];
        if (firstIdx == INVALID_ID)
        {
            emptyBuckets++;
            continue;
        }

        printf("Bucket[%3zu]: ", i);

        // Print linked list
        const Node* cur = GetNode(firstIdx);
        size_type chainLength = 0;
        size_type maxChainLength = m_size + 1; // Prevent infinite loop

        while (cur && chainLength < maxChainLength)
        {
            printf("[%zu", cur->m_self);

            // Print key information
            try
            {
                auto key = m_getKey(cur->m_value);
                printf("(k:");
                if (std::is_arithmetic<decltype(key)>::value)
                {
                    if (std::is_integral<decltype(key)>::value)
                    {
                        printf("%lld", (long long)key);
                    }
                    else
                    {
                        printf("%.2f", (double)key);
                    }
                }
                else
                {
                    printf("?");
                }
                printf(")");
            }
            catch (...)
            {
                printf("(k:?)");
            }

            printf("]");
            totalNodes++;
            chainLength++;

            if (cur->m_next != INVALID_ID)
            {
                printf(" -> ");
                cur = GetNode(cur->m_next);
            }
            else
            {
                break;
            }
        }

        if (chainLength >= maxChainLength)
        {
            printf(" ... (Loop detected!)");
        }

        printf(" (Length: %zu)\n", chainLength);
    }

    printf("=====================================\n");
    printf("Statistics:\n");
    printf("  Non-empty buckets: %zu\n", MAX_SIZE - emptyBuckets);
    printf("  Empty buckets: %zu\n", emptyBuckets);
    printf("  Total traversed nodes: %zu\n", totalNodes);
    printf("  Recorded size: %zu\n", m_size);

    if (totalNodes != m_size)
    {
        printf("  Warning: Traversed nodes count doesn't match recorded size!\n");
    }

    // Print free list
    printf("\nFree list: ");
    if (m_firstFreeIdx == INVALID_ID)
    {
        printf("Empty\n");
    }
    else
    {
        auto pBuckets = GetBuckets();
        int freeIdx = m_firstFreeIdx;
        size_type freeCount = 0;
        size_type maxFreeCount = MAX_SIZE; // Prevent infinite loop

        while (freeIdx != INVALID_ID && freeCount < maxFreeCount)
        {
            printf("[%d]", freeIdx);
            freeCount++;

            if (freeIdx >= 0 && freeIdx < MAX_SIZE)
            {
                freeIdx = pBuckets[freeIdx].m_next;
                if (freeIdx != INVALID_ID)
                {
                    printf(" -> ");
                }
            }
            else
            {
                printf(" (Invalid index!)");
                break;
            }
        }

        if (freeCount >= maxFreeCount)
        {
            printf(" ... (Loop detected!)");
        }

        printf(" (Free nodes: %zu)\n", freeCount);

        size_type expectedFreeCount = MAX_SIZE - m_size;
        if (freeCount != expectedFreeCount)
        {
            printf("  Warning: Free nodes count %zu doesn't match expected %zu!\n", freeCount, expectedFreeCount);
        }
    }

    // 打印链表顺序（如果链表不为空）
    printf("\n=== Insertion Order List (Linked List) ===\n");
    if (m_listHead != INVALID_ID)
    {
        printf("List Head: %d, List Tail: %d\n", m_listHead, m_listTail);
        printf("Insertion order: ");
        auto pNode = GetNode(m_listHead);
        size_type listCount = 0;
        size_type maxListCount = m_size + 1;

        while (pNode && listCount < maxListCount)
        {
            printf("[%zu", pNode->m_self);

            // 打印键值信息
            try
            {
                auto key = m_getKey(pNode->m_value);
                printf("(k:");
                if (std::is_arithmetic<decltype(key)>::value)
                {
                    if (std::is_integral<decltype(key)>::value)
                    {
                        printf("%lld", (long long)key);
                    }
                    else
                    {
                        printf("%.2f", (double)key);
                    }
                }
                else
                {
                    printf("?");
                }
                printf(")");
            }
            catch (...)
            {
                printf("(k:?)");
            }

            // 显示链表指针信息
            printf(",p:%d,n:%d", pNode->m_listPrev, pNode->m_listNext);
            printf("]");

            listCount++;

            if (pNode->m_listNext != INVALID_ID)
            {
                printf(" -> ");
                pNode = GetNode(pNode->m_listNext);
            }
            else
            {
                break;
            }
        }

        if (listCount >= maxListCount)
        {
            printf(" ... (List loop detected!)");
        }

        printf("\n");
        printf("List statistics: %zu nodes", listCount);

        if (listCount != m_size)
        {
            printf(" (Warning: List count %zu != hash size %zu)", listCount, m_size);
        }

        printf("\n");

        // 打印反向链表验证
        printf("Reverse order verification: ");
        auto pTailNode = GetNode(m_listTail);
        size_type reverseCount = 0;

        while (pTailNode && reverseCount < maxListCount)
        {
            printf("[%zu]", pTailNode->m_self);
            reverseCount++;

            if (pTailNode->m_listPrev != INVALID_ID)
            {
                if (reverseCount < 5) // 只显示前几个，避免输出太长
                {
                    printf(" <- ");
                    pTailNode = GetNode(pTailNode->m_listPrev);
                }
                else
                {
                    printf(" <- ...");
                    break;
                }
            }
            else
            {
                break;
            }
        }

        if (reverseCount >= maxListCount)
        {
            printf(" (Reverse loop detected!)");
        }

        printf(" (%zu nodes)\n", reverseCount);

        if (reverseCount != listCount)
        {
            printf("Warning: Forward count %zu != Reverse count %zu\n", listCount, reverseCount);
        }
    }
    else
    {
        printf("List is empty (Head: %d, Tail: %d)\n", m_listHead, m_listTail);

        if (m_listTail != INVALID_ID)
        {
            printf("Warning: Head is INVALID_ID but tail is %d\n", m_listTail);
        }
    }

    printf("LRU Mode: %s\n", m_enableLRU ? "Enabled" : "Disabled");
    printf("Insert Head Mode: %s\n", m_enableInsertHead ? "Enabled" : "Disabled");
    printf("==========================================\n");
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::print_detailed() const
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());

    printf("\n=== NFShmHashTableWithList Detailed View ===\n");
    printf("Size: %zu, Max Size: %d, First Free Index: %d\n", m_size, MAX_SIZE, m_firstFreeIdx);
    printf("=====================================\n");

    auto pBuckets = GetBuckets();

    // Print all node states
    printf("Node Status Table:\n");
    printf("Index Valid SelfRef  Next    Value/Key Info\n");
    printf("----- ----- -------  ----    --------------\n");

    for (int i = 0; i < MAX_SIZE; ++i)
    {
        printf("%5d %5s %7zu %6d  ", i, pBuckets[i].m_valid ? "Yes" : "No", pBuckets[i].m_self, pBuckets[i].m_next);

        if (pBuckets[i].m_valid)
        {
            try
            {
                // Try to get key-value info (assuming key can be converted to string or number)
                auto key = m_getKey(pBuckets[i].m_value);
                printf("Key: ");

                // Print based on key type
                if (std::is_arithmetic<decltype(key)>::value)
                {
                    if (std::is_integral<decltype(key)>::value)
                    {
                        printf("%lld", (long long)key);
                    }
                    else
                    {
                        printf("%.2f", (double)key);
                    }
                }
                else
                {
                    printf("(Complex type)");
                }

                // Calculate and show expected bucket
                size_type expectedBucket = BktNumKey(key);
                printf(", Expected bucket: %zu", expectedBucket);
            }
            catch (...)
            {
                printf("(Cannot get key info)");
            }
        }
        else
        {
            printf("(Free node)");
        }

        printf("\n");
    }

    printf("\nBucket Chain Details:\n");
    printf("=====================================\n");

    for (size_type i = 0; i < MAX_SIZE; ++i)
    {
        int firstIdx = m_bucketsFirstIdx[i];
        if (firstIdx == INVALID_ID)
            continue;

        printf("Bucket[%3zu] -> ", i);

        const Node* cur = GetNode(firstIdx);
        size_type chainLength = 0;
        size_type maxChainLength = m_size + 1;

        while (cur && chainLength < maxChainLength)
        {
            printf("Node%zu", cur->m_self);

            if (cur->m_valid)
            {
                try
                {
                    auto key = m_getKey(cur->m_value);
                    printf("(");

                    if (std::is_arithmetic<decltype(key)>::value)
                    {
                        if (std::is_integral<decltype(key)>::value)
                        {
                            printf("k:%lld", (long long)key);
                        }
                        else
                        {
                            printf("k:%.2f", (double)key);
                        }
                    }
                    else
                    {
                        printf("k:?");
                    }
                    printf(")");
                }
                catch (...)
                {
                    printf("(k:?)");
                }
            }
            else
            {
                printf("(Invalid!)");
            }

            chainLength++;

            if (cur->m_next != INVALID_ID)
            {
                printf(" -> ");
                cur = GetNode(cur->m_next);
            }
            else
            {
                break;
            }
        }

        if (chainLength >= maxChainLength)
        {
            printf(" ... (Loop!)");
        }

        printf("\n");
    }

    printf("=====================================\n\n");
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::print_simple() const
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());

    printf("\n=== Hash Table Simple View ===\n");
    printf("Size: %zu/%d, Free head: %d\n", m_size, MAX_SIZE, m_firstFreeIdx);

    // Only show non-empty buckets
    size_type nonEmptyBuckets = 0;
    for (size_type i = 0; i < MAX_SIZE; ++i)
    {
        if (m_bucketsFirstIdx[i] != INVALID_ID)
        {
            nonEmptyBuckets++;
            printf("%zu: ", i);

            const Node* cur = GetNode(m_bucketsFirstIdx[i]);
            size_type count = 0;
            while (cur && count < 10) // Show at most 10 nodes
            {
                printf("%zu", cur->m_self);

                // Print key information
                try
                {
                    auto key = m_getKey(cur->m_value);
                    printf("(");
                    if (std::is_arithmetic<decltype(key)>::value)
                    {
                        if (std::is_integral<decltype(key)>::value)
                        {
                            printf("%lld", (long long)key);
                        }
                        else
                        {
                            printf("%.2f", (double)key);
                        }
                    }
                    else
                    {
                        printf("?");
                    }
                    printf(")");
                }
                catch (...)
                {
                    printf("(?)");
                }

                count++;

                if (cur->m_next != INVALID_ID)
                {
                    printf("->");
                    cur = GetNode(cur->m_next);
                }
                else
                {
                    break;
                }
            }

            if (count >= 10)
            {
                printf("...");
            }

            printf(" (%zu items)\n", count);
        }
    }

    if (nonEmptyBuckets == 0)
    {
        printf("(All buckets are empty)\n");
    }

    printf("Non-empty buckets: %zu, Load factor: %.2f\n", nonEmptyBuckets, (double)m_size / MAX_SIZE);
    printf("==============================\n\n");
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::InitializeBuckets()
{
    m_size = 0;
    m_firstFreeIdx = 0;
    auto pBuckets = GetBuckets();
    for (int i = 0; i < MAX_SIZE; ++i)
    {
        pBuckets[i].m_next = i + 1;
        pBuckets[i].m_valid = false;
        pBuckets[i].m_self = i;
        pBuckets[i].m_listPrev = INVALID_ID;
        pBuckets[i].m_listNext = INVALID_ID;
    }

    pBuckets[MAX_SIZE - 1].m_next = INVALID_ID;

    for (int i = 0; i < MAX_SIZE; ++i)
    {
        m_bucketsFirstIdx[i] = INVALID_ID;
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::BktNumKey(const key_type& key) const
{
    return BktNumKey(key, MAX_SIZE);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::BktNum(const value_type& obj) const
{
    return BktNumKey(m_getKey(obj));
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::BktNumKey(const key_type& key, size_t n) const
{
    CHECK_EXPR(n > 0, 0, "Bucket count cannot be zero, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(n <= MAX_SIZE, 0, "Bucket count %zu exceeds MAX_SIZE %d, TRACE_STACK:%s", n, MAX_SIZE, TRACE_STACK());

    size_t hashValue = m_hash(key);
    return hashValue % n;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::size_type NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MBktNum(const value_type& obj, size_t n) const
{
    return BktNumKey(m_getKey(obj), n);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::NewNode(const value_type& obj)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, nullptr, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR(!full(), nullptr, "HashTable is full, cannot create new node, TRACE_STACK:%s", TRACE_STACK());

    Node* pNode = CreateNode();
    if (pNode)
    {
        CHECK_EXPR(pNode->m_valid == false, nullptr, "Node should be invalid before initialization, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, nullptr, "Node self index out of range: %zu, TRACE_STACK:%s", pNode->m_self, TRACE_STACK());

        pNode->m_valid = true;
        pNode->m_next = INVALID_ID;

        try
        {
            std::_Construct(&pNode->m_value, obj);

            // 新增：将新创建的节点添加到链表尾部
            if (m_enableInsertHead)
            {
                AddToListHead(pNode);
            }
            else
            {
                AddToListTail(pNode);
            }
        }
        catch (...)
        {
            // 如果构造失败，回滚状态
            pNode->m_valid = false;
            pNode->m_next = INVALID_ID;
            RecycleNode(pNode);
            return nullptr;
        }
    }

    return pNode;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::DeleteNode(Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Node is already invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Node self index out of range: %zu, TRACE_STACK:%s", pNode->m_self, TRACE_STACK());

    // 新增：在删除节点前先从链表中移除
    RemoveFromList(pNode);

    try
    {
        std::_Destroy(&pNode->m_value);
    }
    catch (...)
    {
        // 即使析构失败，也要回收节点
    }
    RecycleNode(pNode);
}

template <class Val, class Key, int MAX_SIZE, class HF, class Ex, class Eq>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HF, Ex, Eq>::CopyFrom(const NFShmHashTableWithList& ht)
{
    if (this == &ht)
        return;

    clear();

    // 复制LRU设置
    m_enableLRU = ht.m_enableLRU;
    m_enableInsertHead = ht.m_enableInsertHead;

    // 按原始链表顺序复制元素以保持插入顺序
    auto pListNode = ht.GetNode(ht.m_listHead);
    while (pListNode)
    {
        // NewNode会自动将节点添加到链表尾部，保持插入顺序
        insert_equal(pListNode->m_value);
        pListNode = ht.GetNode(pListNode->m_listNext);
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::value_type& NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::at(const key_type& key)
{
    iterator it = find(key);
    if (it == end())
    {
        LOG_ERR(0, -1, "NFShmHashTableWithList::at: key not found, TRACE_STACK:%s", TRACE_STACK());
        return m_staticError;
    }
    return *it;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
const typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::value_type& NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::at(const key_type& key) const
{
    const_iterator it = find(key);
    if (it == end())
    {
        LOG_ERR(0, -1, "NFShmHashTableWithList::at: key not found, TRACE_STACK:%s", TRACE_STACK());
        return m_staticError;
    }
    return *it;
}

// ==================== 链表迭代器实现 ====================

/**
 * @brief Hash表链表迭代器（按插入顺序遍历）
 * @tparam Val 值类型
 * @tparam Key 键类型
 * @tparam MAX_SIZE 最大容量
 * @tparam HashFcn 哈希函数类型
 * @tparam ExtractKey 键提取函数类型
 * @tparam EqualKey 键比较函数类型
 *
 * 用于按插入顺序遍历哈希表中的元素，提供链表式的访问接口
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListListIterator
{
    // ==================== STL兼容类型定义 ====================
    typedef NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> Hashtable;
    typedef NFShmHashTableWithListListIterator list_iterator;
    typedef NFShmHashTableWithListConstListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> const_list_iterator;
    typedef NFShmHashTableWithListNode<Val> Node;

    typedef std::forward_iterator_tag iterator_category;
    typedef Val value_type;
    typedef ptrdiff_t difference_type;
    typedef size_t size_type;
    typedef Val& reference;
    typedef Val* pointer;

    // ==================== 成员变量 ====================
    Node* m_curNode; ///< 当前节点指针
    Hashtable* m_hashTable; ///< 所属哈希表指针
    static value_type m_staticError; ///< 错误时返回的静态对象

    // ==================== 构造函数 ====================
    NFShmHashTableWithListListIterator(Node* n, Hashtable* tab) : m_curNode(n), m_hashTable(tab)
    {
    }

    NFShmHashTableWithListListIterator() : m_curNode(nullptr), m_hashTable(nullptr)
    {
    }

    // ==================== STL兼容操作符 ====================
    reference operator*() const
    {
        CHECK_EXPR(m_curNode != nullptr, m_staticError, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, m_staticError, "List iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return m_curNode->m_value;
    }

    pointer operator->() const
    {
        CHECK_EXPR(m_curNode != nullptr, &m_staticError, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, &m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, &m_staticError, "List iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return &(m_curNode->m_value);
    }

    /// @brief 前置递增操作符，移动到链表中下一个元素
    list_iterator& operator++()
    {
        CHECK_EXPR(m_curNode != nullptr, *this, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, *this, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, *this, "Current node is invalid, TRACE_STACK:%s", TRACE_STACK());

        if (m_curNode->m_listNext != INVALID_ID)
        {
            CHECK_EXPR(m_curNode->m_listNext >= 0 && m_curNode->m_listNext < MAX_SIZE, *this, "Next node index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_curNode->m_listNext, MAX_SIZE, TRACE_STACK());
            auto pNextNode = m_hashTable->GetNode(m_curNode->m_listNext);
            CHECK_EXPR(pNextNode != nullptr, *this, "Next node is null at index %d, TRACE_STACK:%s", m_curNode->m_listNext, TRACE_STACK());
            CHECK_EXPR(pNextNode->m_listPrev == m_curNode->m_self, *this, "Next node prev mismatch: expected %zu, got %d, TRACE_STACK:%s", m_curNode->m_self, pNextNode->m_listPrev, TRACE_STACK());
            m_curNode = pNextNode;
        }
        else
        {
            // 验证当前节点确实是尾节点
            CHECK_EXPR(m_curNode->m_self == m_hashTable->m_listTail, *this, "Node claims to be tail but list tail is different: node:%zu, tail:%d, TRACE_STACK:%s", m_curNode->m_self, m_hashTable->m_listTail, TRACE_STACK());
            m_curNode = nullptr; // 已到达链表尾部
        }
        return *this;
    }

    /// @brief 后置递增操作符
    list_iterator operator++(int)
    {
        list_iterator tmp = *this;
        ++*this;
        return tmp;
    }

    /// @brief 前置递减操作符，移动到链表中前一个元素
    list_iterator& operator--()
    {
        CHECK_EXPR(m_curNode != nullptr, *this, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, *this, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, *this, "Current node is invalid, TRACE_STACK:%s", TRACE_STACK());

        if (m_curNode->m_listPrev != INVALID_ID)
        {
            CHECK_EXPR(m_curNode->m_listPrev >= 0 && m_curNode->m_listPrev < MAX_SIZE, *this, "Prev node index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_curNode->m_listPrev, MAX_SIZE, TRACE_STACK());
            auto pPrevNode = m_hashTable->GetNode(m_curNode->m_listPrev);
            CHECK_EXPR(pPrevNode != nullptr, *this, "Prev node is null at index %d, TRACE_STACK:%s", m_curNode->m_listPrev, TRACE_STACK());
            CHECK_EXPR(pPrevNode->m_listNext == m_curNode->m_self, *this, "Prev node next mismatch: expected %zu, got %d, TRACE_STACK:%s", m_curNode->m_self, pPrevNode->m_listNext, TRACE_STACK());
            m_curNode = pPrevNode;
        }
        else
        {
            // 验证当前节点确实是头结点
            CHECK_EXPR(m_curNode->m_self == m_hashTable->m_listHead, *this, "Node claims to be head but list head is different: node:%zu, head:%d, TRACE_STACK:%s", m_curNode->m_self, m_hashTable->m_listHead, TRACE_STACK());
            m_curNode = nullptr; // 已到达链表头部
        }
        return *this;
    }

    /// @brief 后置递减操作符
    list_iterator operator--(int)
    {
        list_iterator tmp = *this;
        --*this;
        return tmp;
    }

    /// @brief 相等比较操作符
    bool operator==(const list_iterator& it) const { return m_curNode == it.m_curNode; }

    /// @brief 不等比较操作符
    bool operator!=(const list_iterator& it) const { return m_curNode != it.m_curNode; }
};

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
Val NFShmHashTableWithListListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::m_staticError = Val();

/**
 * @brief Hash表常量链表迭代器
 * @note 与非常量链表迭代器类似，但提供const访问
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
struct NFShmHashTableWithListConstListIterator
{
    // ==================== STL兼容类型定义 ====================
    typedef NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> Hashtable;
    typedef NFShmHashTableWithListListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey> list_iterator;
    typedef NFShmHashTableWithListConstListIterator const_list_iterator;
    typedef NFShmHashTableWithListNode<Val> Node;

    typedef std::forward_iterator_tag iterator_category;
    typedef Val value_type;
    typedef ptrdiff_t difference_type;
    typedef size_t size_type;
    typedef const Val& reference;
    typedef const Val* pointer;

    // ==================== 成员变量 ====================
    const Node* m_curNode; ///< 当前节点常量指针
    const Hashtable* m_hashTable; ///< 所属哈希表常量指针
    static value_type m_staticError;

    // ==================== 构造函数 ====================
    NFShmHashTableWithListConstListIterator(const Node* n, const Hashtable* tab) : m_curNode(n), m_hashTable(tab)
    {
    }

    NFShmHashTableWithListConstListIterator() : m_curNode(nullptr), m_hashTable(nullptr)
    {
    }

    /**
     * @brief 从非常量链表迭代器构造
     * @param it 非常量链表迭代器
     */
    NFShmHashTableWithListConstListIterator(const list_iterator& it) : m_curNode(it.m_curNode), m_hashTable(it.m_hashTable)
    {
    }

    // ==================== STL兼容操作符 ====================
    reference operator*() const
    {
        CHECK_EXPR(m_curNode != nullptr, m_staticError, "Const list iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, m_staticError, "Const list iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return m_curNode->m_value;
    }

    pointer operator->() const
    {
        CHECK_EXPR(m_curNode != nullptr, &m_staticError, "Const list iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, &m_staticError, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, &m_staticError, "Const list iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());
        return &(m_curNode->m_value);
    }

    const_list_iterator& operator++()
    {
        CHECK_EXPR(m_curNode != nullptr, *this, "Const list iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, *this, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, *this, "Current node is invalid, TRACE_STACK:%s", TRACE_STACK());

        if (m_curNode->m_listNext != INVALID_ID)
        {
            CHECK_EXPR(m_curNode->m_listNext >= 0 && m_curNode->m_listNext < MAX_SIZE, *this, "Next node index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_curNode->m_listNext, MAX_SIZE, TRACE_STACK());
            auto pNextNode = m_hashTable->GetNode(m_curNode->m_listNext);
            CHECK_EXPR(pNextNode != nullptr, *this, "Next node is null at index %d, TRACE_STACK:%s", m_curNode->m_listNext, TRACE_STACK());
            CHECK_EXPR(pNextNode->m_listPrev == m_curNode->m_self, *this, "Next node prev mismatch: expected %zu, got %d, TRACE_STACK:%s", m_curNode->m_self, pNextNode->m_listPrev, TRACE_STACK());
            m_curNode = pNextNode;
        }
        else
        {
            // 验证当前节点确实是尾节点
            CHECK_EXPR(m_curNode->m_self == m_hashTable->m_listTail, *this, "Node claims to be tail but list tail is different: node:%zu, tail:%d, TRACE_STACK:%s", m_curNode->m_self, m_hashTable->m_listTail, TRACE_STACK());
            m_curNode = nullptr; // 已到达链表尾部
        }
        return *this;
    }

    const_list_iterator operator++(int)
    {
        const_list_iterator tmp = *this;
        ++*this;
        return tmp;
    }

    /// @brief 前置递减操作符，移动到链表中前一个元素
    const_list_iterator& operator--()
    {
        CHECK_EXPR(m_curNode != nullptr, *this, "Const list iterator is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_hashTable != nullptr, *this, "HashTable is null, TRACE_STACK:%s", TRACE_STACK());
        CHECK_EXPR(m_curNode->m_valid, *this, "Current node is invalid, TRACE_STACK:%s", TRACE_STACK());

        if (m_curNode->m_listPrev != INVALID_ID)
        {
            CHECK_EXPR(m_curNode->m_listPrev >= 0 && m_curNode->m_listPrev < MAX_SIZE, *this, "Prev node index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_curNode->m_listPrev, MAX_SIZE, TRACE_STACK());
            auto pPrevNode = m_hashTable->GetNode(m_curNode->m_listPrev);
            CHECK_EXPR(pPrevNode != nullptr, *this, "Prev node is null at index %d, TRACE_STACK:%s", m_curNode->m_listPrev, TRACE_STACK());
            CHECK_EXPR(pPrevNode->m_listNext == m_curNode->m_self, *this, "Prev node next mismatch: expected %zu, got %d, TRACE_STACK:%s", m_curNode->m_self, pPrevNode->m_listNext, TRACE_STACK());
            m_curNode = pPrevNode;
        }
        else
        {
            // 验证当前节点确实是头结点
            CHECK_EXPR(m_curNode->m_self == m_hashTable->m_listHead, *this, "Node claims to be head but list head is different: node:%zu, head:%d, TRACE_STACK:%s", m_curNode->m_self, m_hashTable->m_listHead, TRACE_STACK());
            m_curNode = nullptr; // 已到达链表头部
        }
        return *this;
    }

    /// @brief 后置递减操作符
    const_list_iterator operator--(int)
    {
        const_list_iterator tmp = *this;
        --*this;
        return tmp;
    }

    bool operator==(const const_list_iterator& it) const { return m_curNode == it.m_curNode; }
    bool operator!=(const const_list_iterator& it) const { return m_curNode != it.m_curNode; }
};

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
Val NFShmHashTableWithListConstListIterator<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::m_staticError = Val();

// ==================== 链表管理函数实现 ====================

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::InitializeList()
{
    m_listHead = INVALID_ID;
    m_listTail = INVALID_ID;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::AddToListTail(Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Node self index out of range: %zu, valid range [0, %d), TRACE_STACK:%s", pNode->m_self, MAX_SIZE, TRACE_STACK());

    // 检查节点是否已经在链表中
    CHECK_EXPR_RE_VOID(pNode->m_listPrev == INVALID_ID && pNode->m_listNext == INVALID_ID, "Node is already in list, prev:%d, next:%d, TRACE_STACK:%s", pNode->m_listPrev, pNode->m_listNext, TRACE_STACK());

    // 检查链表状态一致性
    if (m_listHead == INVALID_ID)
    {
        CHECK_EXPR_RE_VOID(m_listTail == INVALID_ID, "List head is INVALID_ID but tail is not INVALID_ID: %d, TRACE_STACK:%s", m_listTail, TRACE_STACK());
    }
    else
    {
        CHECK_EXPR_RE_VOID(m_listTail != INVALID_ID, "List head is not INVALID_ID but tail is INVALID_ID, head:%d, TRACE_STACK:%s", m_listHead, TRACE_STACK());
        CHECK_EXPR_RE_VOID(m_listHead >= 0 && m_listHead < MAX_SIZE, "List head index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listHead, MAX_SIZE, TRACE_STACK());
        CHECK_EXPR_RE_VOID(m_listTail >= 0 && m_listTail < MAX_SIZE, "List tail index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listTail, MAX_SIZE, TRACE_STACK());
    }

    pNode->m_listPrev = m_listTail;
    pNode->m_listNext = INVALID_ID;

    if (m_listTail != INVALID_ID)
    {
        // 链表不为空，更新尾节点的next指针
        auto pTailNode = GetNode(m_listTail);
        CHECK_EXPR_RE_VOID(pTailNode != nullptr, "Tail node is null at index %d, TRACE_STACK:%s", m_listTail, TRACE_STACK());
        CHECK_EXPR_RE_VOID(pTailNode->m_listNext == INVALID_ID, "Tail node next should be INVALID_ID but is %d, TRACE_STACK:%s", pTailNode->m_listNext, TRACE_STACK());

        pTailNode->m_listNext = pNode->m_self;
    }
    else
    {
        // 链表为空，更新头指针
        m_listHead = pNode->m_self;
    }

    m_listTail = pNode->m_self;

    // 验证链表操作后的状态
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "List head or tail is INVALID_ID after adding node, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::AddToListHead(Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Node self index out of range: %zu, valid range [0, %d), TRACE_STACK:%s", pNode->m_self, MAX_SIZE, TRACE_STACK());

    // 检查节点是否已经在链表中
    CHECK_EXPR_RE_VOID(pNode->m_listPrev == INVALID_ID && pNode->m_listNext == INVALID_ID, "Node is already in list, prev:%d, next:%d, TRACE_STACK:%s", pNode->m_listPrev, pNode->m_listNext, TRACE_STACK());

    // 检查链表状态一致性
    if (m_listHead == INVALID_ID)
    {
        CHECK_EXPR_RE_VOID(m_listTail == INVALID_ID, "List head is INVALID_ID but tail is not INVALID_ID: %d, TRACE_STACK:%s", m_listTail, TRACE_STACK());
    }
    else
    {
        CHECK_EXPR_RE_VOID(m_listTail != INVALID_ID, "List head is not INVALID_ID but tail is INVALID_ID, head:%d, TRACE_STACK:%s", m_listHead, TRACE_STACK());
        CHECK_EXPR_RE_VOID(m_listHead >= 0 && m_listHead < MAX_SIZE, "List head index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listHead, MAX_SIZE, TRACE_STACK());
        CHECK_EXPR_RE_VOID(m_listTail >= 0 && m_listTail < MAX_SIZE, "List tail index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listTail, MAX_SIZE, TRACE_STACK());
    }

    pNode->m_listPrev = INVALID_ID;
    pNode->m_listNext = m_listHead;

    if (m_listHead != INVALID_ID)
    {
        // 链表不为空，更新头节点的prev指针
        auto pHeadNode = GetNode(m_listHead);
        CHECK_EXPR_RE_VOID(pHeadNode != nullptr, "Head node is null at index %d, TRACE_STACK:%s", m_listHead, TRACE_STACK());
        CHECK_EXPR_RE_VOID(pHeadNode->m_listPrev == INVALID_ID, "Head node prev should be INVALID_ID but is %d, TRACE_STACK:%s", pHeadNode->m_listPrev, TRACE_STACK());

        pHeadNode->m_listPrev = pNode->m_self;
    }
    else
    {
        // 链表为空，更新尾指针
        m_listTail = pNode->m_self;
    }

    m_listHead = pNode->m_self;

    // 验证链表操作后的状态
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "List head or tail is INVALID_ID after adding node to head, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::RemoveFromList(Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Node self index out of range: %zu, valid range [0, %d), TRACE_STACK:%s", pNode->m_self, MAX_SIZE, TRACE_STACK());

    // 检查链表不为空
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "Cannot remove from empty list, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());

    // 检查链表索引范围
    CHECK_EXPR_RE_VOID(m_listHead >= 0 && m_listHead < MAX_SIZE, "List head index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listHead, MAX_SIZE, TRACE_STACK());
    CHECK_EXPR_RE_VOID(m_listTail >= 0 && m_listTail < MAX_SIZE, "List tail index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listTail, MAX_SIZE, TRACE_STACK());

    if (pNode->m_listPrev != INVALID_ID)
    {
        CHECK_EXPR_RE_VOID(pNode->m_listPrev >= 0 && pNode->m_listPrev < MAX_SIZE, "Node prev index out of range: %d, valid range [0, %d), TRACE_STACK:%s", pNode->m_listPrev, MAX_SIZE, TRACE_STACK());
        auto pPrevNode = GetNode(pNode->m_listPrev);
        CHECK_EXPR_RE_VOID(pPrevNode != nullptr, "Previous node is null at index %d, TRACE_STACK:%s", pNode->m_listPrev, TRACE_STACK());
        CHECK_EXPR_RE_VOID(pPrevNode->m_listNext == pNode->m_self, "Previous node next mismatch: expected %zu, got %d, TRACE_STACK:%s", pNode->m_self, pPrevNode->m_listNext, TRACE_STACK());

        pPrevNode->m_listNext = pNode->m_listNext;
    }
    else
    {
        // 删除的是头节点
        CHECK_EXPR_RE_VOID(m_listHead == pNode->m_self, "Node is not head but has no prev, head:%d, node:%zu, TRACE_STACK:%s", m_listHead, pNode->m_self, TRACE_STACK());
        m_listHead = pNode->m_listNext;
    }

    if (pNode->m_listNext != INVALID_ID)
    {
        CHECK_EXPR_RE_VOID(pNode->m_listNext >= 0 && pNode->m_listNext < MAX_SIZE, "Node next index out of range: %d, valid range [0, %d), TRACE_STACK:%s", pNode->m_listNext, MAX_SIZE, TRACE_STACK());
        auto pNextNode = GetNode(pNode->m_listNext);
        CHECK_EXPR_RE_VOID(pNextNode != nullptr, "Next node is null at index %d, TRACE_STACK:%s", pNode->m_listNext, TRACE_STACK());
        CHECK_EXPR_RE_VOID(pNextNode->m_listPrev == pNode->m_self, "Next node prev mismatch: expected %zu, got %d, TRACE_STACK:%s", pNode->m_self, pNextNode->m_listPrev, TRACE_STACK());

        pNextNode->m_listPrev = pNode->m_listPrev;
    }
    else
    {
        // 删除的是尾节点
        CHECK_EXPR_RE_VOID(m_listTail == pNode->m_self, "Node is not tail but has no next, tail:%d, node:%zu, TRACE_STACK:%s", m_listTail, pNode->m_self, TRACE_STACK());
        m_listTail = pNode->m_listPrev;
    }

    pNode->m_listPrev = INVALID_ID;
    pNode->m_listNext = INVALID_ID;

    // 验证链表操作后的状态
    if (m_listHead == INVALID_ID)
    {
        CHECK_EXPR_RE_VOID(m_listTail == INVALID_ID, "List head is INVALID_ID but tail is not INVALID_ID after removal: %d, TRACE_STACK:%s", m_listTail, TRACE_STACK());
    }
    else
    {
        CHECK_EXPR_RE_VOID(m_listTail != INVALID_ID, "List head is not INVALID_ID but tail is INVALID_ID after removal, head:%d, TRACE_STACK:%s", m_listHead, TRACE_STACK());
        CHECK_EXPR_RE_VOID(m_listHead >= 0 && m_listHead < MAX_SIZE, "List head index out of range after removal: %d, valid range [0, %d), TRACE_STACK:%s", m_listHead, MAX_SIZE, TRACE_STACK());
        CHECK_EXPR_RE_VOID(m_listTail >= 0 && m_listTail < MAX_SIZE, "List tail index out of range after removal: %d, valid range [0, %d), TRACE_STACK:%s", m_listTail, MAX_SIZE, TRACE_STACK());
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToListTail(Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Node self index out of range: %zu, valid range [0, %d), TRACE_STACK:%s", pNode->m_self, MAX_SIZE, TRACE_STACK());

    // 检查链表不为空
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "Cannot move node in empty list, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());

    // 检查链表索引范围
    CHECK_EXPR_RE_VOID(m_listHead >= 0 && m_listHead < MAX_SIZE, "List head index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listHead, MAX_SIZE, TRACE_STACK());
    CHECK_EXPR_RE_VOID(m_listTail >= 0 && m_listTail < MAX_SIZE, "List tail index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listTail, MAX_SIZE, TRACE_STACK());

    // 如果已经是尾节点，无需移动
    if (pNode->m_self == m_listTail)
    {
        // 验证尾节点的一致性
        CHECK_EXPR_RE_VOID(pNode->m_listNext == INVALID_ID, "Tail node next should be INVALID_ID but is %d, TRACE_STACK:%s", pNode->m_listNext, TRACE_STACK());
        return;
    }

    // 先从当前位置移除
    RemoveFromList(pNode);

    // 然后添加到尾部
    AddToListTail(pNode);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToListHead(Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Node self index out of range: %zu, valid range [0, %d), TRACE_STACK:%s", pNode->m_self, MAX_SIZE, TRACE_STACK());

    // 检查链表不为空
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "Cannot move node in empty list, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());

    // 检查链表索引范围
    CHECK_EXPR_RE_VOID(m_listHead >= 0 && m_listHead < MAX_SIZE, "List head index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listHead, MAX_SIZE, TRACE_STACK());
    CHECK_EXPR_RE_VOID(m_listTail >= 0 && m_listTail < MAX_SIZE, "List tail index out of range: %d, valid range [0, %d), TRACE_STACK:%s", m_listTail, MAX_SIZE, TRACE_STACK());

    // 如果已经是头节点，无需移动
    if (pNode->m_self == m_listHead)
    {
        // 验证头节点的一致性
        CHECK_EXPR_RE_VOID(pNode->m_listPrev == INVALID_ID, "Head node prev should be INVALID_ID but is %d, TRACE_STACK:%s", pNode->m_listPrev, TRACE_STACK());
        return;
    }

    // 先从当前位置移除
    RemoveFromList(pNode);

    // 然后添加到头部
    AddToListHead(pNode);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToNodeFront(const_iterator iter, Compare compareFunc)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode != nullptr, "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode->m_valid, "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    // 检查链表不为空
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID)
    {
        return; // 空链表，无需移动
    }

    Node* pSelfNode = const_cast<Node*>(iter.m_curNode);
    const Val& selfValue = pSelfNode->m_value;

    // 遍历链表，找到第一个使compareFunc返回true的节点
    auto pCurrentNode = GetNode(m_listHead);
    size_t maxIterations = m_size + 1; // 防止无限循环
    size_t iterations = 0;

    while (pCurrentNode && iterations < maxIterations)
    {
        if (pCurrentNode != pSelfNode && compareFunc(selfValue, pCurrentNode->m_value))
        {
            // 找到目标位置，将pSelfNode移动到pCurrentNode附近
            MoveToListNodeFront(pSelfNode, pCurrentNode);
            return;
        }

        iterations++;
        pCurrentNode = (pCurrentNode->m_listNext != INVALID_ID) ? GetNode(pCurrentNode->m_listNext) : nullptr;
    }

    // 如果没有找到满足条件的节点，移动到链表尾部
    // 将节点移动到链表尾部（如果不在尾部的话）
    if (pSelfNode->m_self != m_listTail)
    {
        RemoveFromList(pSelfNode);
        AddToListTail(pSelfNode);
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToNodeFront(const_list_iterator iter, Compare compareFunc)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode != nullptr, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode->m_valid, "List iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    // 检查链表不为空
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID)
    {
        return; // 空链表，无需移动
    }

    Node* pSelfNode = const_cast<Node*>(iter.m_curNode);
    const Val& selfValue = pSelfNode->m_value;

    // 遍历链表，找到第一个使compareFunc返回true的节点
    auto pCurrentNode = GetNode(m_listHead);
    size_t maxIterations = m_size + 1; // 防止无限循环
    size_t iterations = 0;

    while (pCurrentNode && iterations < maxIterations)
    {
        if (pCurrentNode != pSelfNode && compareFunc(selfValue, pCurrentNode->m_value))
        {
            // 找到目标位置，将pSelfNode移动到pCurrentNode附近
            MoveToListNodeFront(pSelfNode, pCurrentNode);
            return;
        }

        iterations++;
        pCurrentNode = (pCurrentNode->m_listNext != INVALID_ID) ? GetNode(pCurrentNode->m_listNext) : nullptr;
    }

    // 如果没有找到满足条件的节点，说明应该插入到链表尾部
    // 将节点移动到链表尾部（如果不在尾部的话）
    if (pSelfNode->m_self != m_listTail)
    {
        RemoveFromList(pSelfNode);
        AddToListTail(pSelfNode);
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToNodeBack(const_iterator iter, Compare compareFunc)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode != nullptr, "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode->m_valid, "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    // 检查链表不为空
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID)
    {
        return; // 空链表，无需移动
    }

    Node* pSelfNode = const_cast<Node*>(iter.m_curNode);
    const Val& selfValue = pSelfNode->m_value;

    // 遍历链表，找到第一个使compareFunc返回true的节点
    auto pCurrentNode = GetNode(m_listHead);
    size_t maxIterations = m_size + 1; // 防止无限循环
    size_t iterations = 0;

    while (pCurrentNode && iterations < maxIterations)
    {
        if (pCurrentNode != pSelfNode && compareFunc(selfValue, pCurrentNode->m_value))
        {
            // 找到目标位置，将pSelfNode移动到pCurrentNode附近
            MoveToListNodeBack(pSelfNode, pCurrentNode);
            return;
        }

        iterations++;
        pCurrentNode = (pCurrentNode->m_listNext != INVALID_ID) ? GetNode(pCurrentNode->m_listNext) : nullptr;
    }

    // 如果没有找到满足条件的节点，说明应该插入到链表尾部
    // 将节点移动到链表尾部（如果不在尾部的话）
    if (pSelfNode->m_self != m_listTail)
    {
        RemoveFromList(pSelfNode);
        AddToListTail(pSelfNode);
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToNodeBack(const_list_iterator iter, Compare compareFunc)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode != nullptr, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode->m_valid, "List iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    // 检查链表不为空
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID)
    {
        return; // 空链表，无需移动
    }

    Node* pSelfNode = const_cast<Node*>(iter.m_curNode);
    const Val& selfValue = pSelfNode->m_value;

    // 遍历链表，找到第一个使compareFunc返回true的节点
    auto pCurrentNode = GetNode(m_listHead);
    size_t maxIterations = m_size + 1; // 防止无限循环
    size_t iterations = 0;

    while (pCurrentNode && iterations < maxIterations)
    {
        if (pCurrentNode != pSelfNode && compareFunc(selfValue, pCurrentNode->m_value))
        {
            // 找到目标位置，将pSelfNode移动到pCurrentNode附近
            MoveToListNodeBack(pSelfNode, pCurrentNode);
            return;
        }

        iterations++;
        pCurrentNode = (pCurrentNode->m_listNext != INVALID_ID) ? GetNode(pCurrentNode->m_listNext) : nullptr;
    }

    // 如果没有找到满足条件的节点，说明应该插入到链表尾部
    // 将节点移动到链表尾部（如果不在尾部的话）
    if (pSelfNode->m_self != m_listTail)
    {
        RemoveFromList(pSelfNode);
        AddToListTail(pSelfNode);
    }
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToListNodeFront(Node* pSelf, Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pSelf != nullptr, "Self node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Target node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pSelf->m_valid, "Self node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Target node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pSelf->m_self >= 0 && pSelf->m_self < MAX_SIZE, "Self node index out of range: %zu, TRACE_STACK:%s", pSelf->m_self, TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Target node index out of range: %zu, TRACE_STACK:%s", pNode->m_self, TRACE_STACK());

    // 如果两个节点相同，无需移动
    if (pSelf->m_self == pNode->m_self)
    {
        return;
    }

    // 检查链表不为空
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "Cannot move node in empty list, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());

    // 先从当前位置移除pSelf
    RemoveFromList(pSelf);

    // 将pSelf插入到pNode之前（前面）
    pSelf->m_listPrev = pNode->m_listPrev;
    pSelf->m_listNext = pNode->m_self;

    if (pNode->m_listPrev != INVALID_ID)
    {
        // pNode不是头节点，更新前一个节点的next指针
        auto pPrevNode = GetNode(pNode->m_listPrev);
        CHECK_EXPR_RE_VOID(pPrevNode != nullptr, "Previous node is null at index %d, TRACE_STACK:%s", pNode->m_listPrev, TRACE_STACK());
        pPrevNode->m_listNext = pSelf->m_self;
    }
    else
    {
        // pNode是头节点，更新头指针
        m_listHead = pSelf->m_self;
    }

    pNode->m_listPrev = pSelf->m_self;

    // 验证链表操作后的状态
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "List head or tail is INVALID_ID after moving node, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToListNodeBack(Node* pSelf, Node* pNode)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pSelf != nullptr, "Self node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode != nullptr, "Target node pointer is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pSelf->m_valid, "Self node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_valid, "Target node is invalid, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(pSelf->m_self >= 0 && pSelf->m_self < MAX_SIZE, "Self node index out of range: %zu, TRACE_STACK:%s", pSelf->m_self, TRACE_STACK());
    CHECK_EXPR_RE_VOID(pNode->m_self >= 0 && pNode->m_self < MAX_SIZE, "Target node index out of range: %zu, TRACE_STACK:%s", pNode->m_self, TRACE_STACK());

    // 如果两个节点相同，无需移动
    if (pSelf->m_self == pNode->m_self)
    {
        return;
    }

    // 检查链表不为空
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "Cannot move node in empty list, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());

    // 先从当前位置移除pSelf
    RemoveFromList(pSelf);

    // 将pSelf插入到pNode之后（后面）
    pSelf->m_listPrev = pNode->m_self;
    pSelf->m_listNext = pNode->m_listNext;

    if (pNode->m_listNext != INVALID_ID)
    {
        // pNode不是尾节点，更新后一个节点的prev指针
        auto pNextNode = GetNode(pNode->m_listNext);
        CHECK_EXPR_RE_VOID(pNextNode != nullptr, "Next node is null at index %d, TRACE_STACK:%s", pNode->m_listNext, TRACE_STACK());
        pNextNode->m_listPrev = pSelf->m_self;
    }
    else
    {
        // pNode是尾节点，更新尾指针
        m_listTail = pSelf->m_self;
    }

    pNode->m_listNext = pSelf->m_self;

    // 验证链表操作后的状态
    CHECK_EXPR_RE_VOID(m_listHead != INVALID_ID && m_listTail != INVALID_ID, "List head or tail is INVALID_ID after moving node, head:%d, tail:%d, TRACE_STACK:%s", m_listHead, m_listTail, TRACE_STACK());
}

// ==================== 链表迭代器接口实现 ====================

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_begin()
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, list_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return list_iterator(GetNode(m_listHead), this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_end()
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, list_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return list_iterator(nullptr, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_begin() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, const_list_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return const_list_iterator(GetNode(m_listHead), this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_end() const
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, const_list_iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());
    return const_list_iterator(nullptr, this);
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_cbegin() const
{
    return list_begin();
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::const_list_iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::list_cend() const
{
    return list_end();
}

// ==================== 链表完整性验证函数实现 ====================

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
bool NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::ValidateListIntegrity() const
{
    if (m_init != EN_NF_SHM_STL_INIT_OK)
    {
        return false;
    }

    // 检查空链表情况
    if (m_listHead == INVALID_ID && m_listTail == INVALID_ID)
    {
        return true; // 空链表是合法的
    }

    // 检查非空链表的基本一致性
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID)
    {
        return false; // 头尾指针不一致
    }

    if (m_listHead < 0 || m_listHead >= MAX_SIZE || m_listTail < 0 || m_listTail >= MAX_SIZE)
    {
        return false; // 头尾指针超出范围
    }

    // 从头到尾遍历链表，检查一致性
    int currentIdx = m_listHead;
    int prevIdx = INVALID_ID;
    size_t forwardCount = 0;
    const size_t maxIterations = m_size + 1;

    while (currentIdx != INVALID_ID && forwardCount < maxIterations)
    {
        auto pNode = GetNode(currentIdx);
        if (!pNode)
        {
            return false; // 节点无效
        }

        if (pNode->m_listPrev != prevIdx)
        {
            return false; // 前驱指针不匹配
        }

        prevIdx = currentIdx;
        currentIdx = pNode->m_listNext;
        forwardCount++;
    }

    if (forwardCount >= maxIterations)
    {
        return false; // 可能存在循环
    }

    if (prevIdx != m_listTail)
    {
        return false; // 最后一个节点不是尾节点
    }

    // 从尾到头遍历链表，再次验证
    currentIdx = m_listTail;
    int nextIdx = INVALID_ID;
    size_t backwardCount = 0;

    while (currentIdx != INVALID_ID && backwardCount < maxIterations)
    {
        auto pNode = GetNode(currentIdx);
        if (!pNode)
        {
            return false; // 节点无效
        }

        if (pNode->m_listNext != nextIdx)
        {
            return false; // 后继指针不匹配
        }

        nextIdx = currentIdx;
        currentIdx = pNode->m_listPrev;
        backwardCount++;
    }

    if (backwardCount >= maxIterations)
    {
        return false; // 可能存在循环
    }

    if (nextIdx != m_listHead)
    {
        return false; // 最后一个节点不是头节点
    }

    if (forwardCount != backwardCount)
    {
        return false; // 前向和后向遍历的节点数不匹配
    }

    // 验证链表中的所有节点都是有效的，且在哈希表中存在
    currentIdx = m_listHead;
    size_t validNodeCount = 0;

    while (currentIdx != INVALID_ID)
    {
        auto pNode = GetNode(currentIdx);
        if (!pNode || !pNode->m_valid)
        {
            return false;
        }

        validNodeCount++;
        currentIdx = pNode->m_listNext;
    }

    // 检查所有有效节点是否都在链表中
    size_t hashTableValidNodes = 0;
    for (int i = 0; i < MAX_SIZE; i++)
    {
        auto pNode = GetNode(i);
        if (pNode && pNode->m_valid)
        {
            hashTableValidNodes++;
        }
    }

    if (validNodeCount != hashTableValidNodes)
    {
        return false; // 链表中的有效节点数与哈希表中的不匹配
    }

    return true;
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::print_list() const
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "not init, TRACE_STACK:%s", TRACE_STACK());

    printf("\n=== Insertion Order List Details ===\n");
    printf("LRU Mode: %s\n", m_enableLRU ? "Enabled" : "Disabled");
    printf("Insert Head Mode: %s\n", m_enableInsertHead ? "Enabled" : "Disabled");
    printf("List Head: %d, List Tail: %d\n", m_listHead, m_listTail);

    // 验证链表完整性
    bool listIntegrityOK = ValidateListIntegrity();
    printf("List Integrity: %s\n", listIntegrityOK ? "OK" : "FAILED");

    if (m_listHead != INVALID_ID)
    {
        printf("\n--- Forward Traversal (Insertion Order) ---\n");
        auto pNode = GetNode(m_listHead);
        size_type listCount = 0;
        size_type maxListCount = m_size + 1;

        while (pNode && listCount < maxListCount)
        {
            printf("Node[%zu]: ", pNode->m_self);

            // 打印键值信息
            try
            {
                auto key = m_getKey(pNode->m_value);
                printf("Key=");
                if (std::is_arithmetic<decltype(key)>::value)
                {
                    if (std::is_integral<decltype(key)>::value)
                    {
                        printf("%lld", (long long)key);
                    }
                    else
                    {
                        printf("%.2f", (double)key);
                    }
                }
                else
                {
                    printf("(complex)");
                }
            }
            catch (...)
            {
                printf("Key=(error)");
            }

            // 显示链表指针信息
            printf(", Prev=%d, Next=%d", pNode->m_listPrev, pNode->m_listNext);

            // 计算在哪个桶中
            try
            {
                size_type bucket = BktNum(pNode->m_value);
                printf(", Bucket=%zu", bucket);
            }
            catch (...)
            {
                printf(", Bucket=(error)");
            }

            printf("\n");

            listCount++;

            if (pNode->m_listNext != INVALID_ID)
            {
                pNode = GetNode(pNode->m_listNext);
            }
            else
            {
                break;
            }
        }

        if (listCount >= maxListCount)
        {
            printf("... (Loop detected, stopped at %zu nodes)\n", listCount);
        }

        printf("\nForward traversal: %zu nodes\n", listCount);

        if (listCount != m_size)
        {
            printf("WARNING: List count %zu != hash table size %zu\n", listCount, m_size);
        }

        // 打印反向遍历验证
        printf("\n--- Backward Traversal (LRU Order) ---\n");
        auto pTailNode = GetNode(m_listTail);
        size_type reverseCount = 0;

        while (pTailNode && reverseCount < maxListCount)
        {
            printf("Node[%zu]: ", pTailNode->m_self);

            // 打印键值信息
            try
            {
                auto key = m_getKey(pTailNode->m_value);
                printf("Key=");
                if (std::is_arithmetic<decltype(key)>::value)
                {
                    if (std::is_integral<decltype(key)>::value)
                    {
                        printf("%lld", (long long)key);
                    }
                    else
                    {
                        printf("%.2f", (double)key);
                    }
                }
                else
                {
                    printf("(complex)");
                }
            }
            catch (...)
            {
                printf("Key=(error)");
            }

            printf(", Prev=%d, Next=%d\n", pTailNode->m_listPrev, pTailNode->m_listNext);

            reverseCount++;

            if (pTailNode->m_listPrev != INVALID_ID)
            {
                pTailNode = GetNode(pTailNode->m_listPrev);
            }
            else
            {
                break;
            }
        }

        if (reverseCount >= maxListCount)
        {
            printf("... (Reverse loop detected, stopped at %zu nodes)\n", reverseCount);
        }

        printf("\nBackward traversal: %zu nodes\n", reverseCount);

        if (reverseCount != listCount)
        {
            printf("WARNING: Forward count %zu != Backward count %zu\n", listCount, reverseCount);
        }

        // 打印简化的插入顺序
        printf("\n--- Insertion Order Summary ---\n");
        printf("First -> Last: ");
        pNode = GetNode(m_listHead);
        size_type summaryCount = 0;

        while (pNode && summaryCount < 10) // 只显示前10个
        {
            printf("%zu", pNode->m_self);
            summaryCount++;

            if (pNode->m_listNext != INVALID_ID && summaryCount < 10)
            {
                printf(" -> ");
                pNode = GetNode(pNode->m_listNext);
            }
            else
            {
                if (pNode->m_listNext != INVALID_ID)
                {
                    printf(" -> ... -> %d", m_listTail);
                }
                break;
            }
        }
        printf("\n");
    }
    else
    {
        printf("List is empty\n");

        if (m_listTail != INVALID_ID)
        {
            printf("WARNING: Head is INVALID_ID but tail is %d\n", m_listTail);
        }

        // 检查是否有孤立的链表节点
        printf("\nChecking for orphaned list nodes...\n");
        bool foundOrphans = false;
        for (int i = 0; i < MAX_SIZE; i++)
        {
            auto pNode = GetNode(i);
            if (pNode && (pNode->m_listPrev != INVALID_ID || pNode->m_listNext != INVALID_ID))
            {
                if (!foundOrphans)
                {
                    printf("WARNING: Found orphaned list nodes:\n");
                    foundOrphans = true;
                }
                printf("  Node[%d]: Prev=%d, Next=%d\n", i, pNode->m_listPrev, pNode->m_listNext);
            }
        }

        if (!foundOrphans)
        {
            printf("No orphaned list nodes found.\n");
        }
    }

    printf("=====================================\n");
}

/**
 * @brief 插入排序实现 - 直接在链表上操作
 * @param comp 比较函数
 * @details 使用插入排序算法对链表进行原地排序
 * @note 时间复杂度：O(n²)，空间复杂度：O(1)
 * @note 稳定排序：相等元素保持原有顺序
 * @note 算法思路：
 *       1. 将链表视为已排序部分（开始只有第一个元素）和未排序部分
 *       2. 依次从未排序部分取出元素，插入到已排序部分的正确位置
 *       3. 通过调整链表指针完成元素移动
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insertion_sort(StrictWeakOrdering comp)
{
    // 空链表或单元素链表已经是排序的
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_listHead == m_listTail)
    {
        return;
    }

    // 从第二个节点开始处理（第一个节点认为已排序）
    Node* currentNode = GetNode(m_listHead);
    if (currentNode == nullptr || currentNode->m_listNext == INVALID_ID)
    {
        return;
    }

    int currentIdx = currentNode->m_listNext;

    while (currentIdx != INVALID_ID)
    {
        Node* nodeToInsert = GetNode(currentIdx);
        if (nodeToInsert == nullptr)
        {
            break;
        }

        // 保存下一个要处理的节点
        int nextIdx = nodeToInsert->m_listNext;

        // 在已排序部分找到插入位置
        int insertAfterIdx = INVALID_ID; // 要插入到这个节点之后，INVALID_ID表示插入到头部
        Node* searchNode = GetNode(m_listHead);

        // 从头开始搜索插入位置
        while (searchNode != nullptr && searchNode != nodeToInsert)
        {
            // 如果nodeToInsert应该插入在searchNode之前，停止搜索
            if (comp(nodeToInsert->m_value, searchNode->m_value))
            {
                // 找到了插入位置，应该插入在searchNode之前
                break;
            }

            // nodeToInsert应该在searchNode之后，继续搜索
            insertAfterIdx = searchNode->m_self;

            // 移动到下一个节点
            if (searchNode->m_listNext != INVALID_ID && searchNode->m_listNext != nodeToInsert->m_self)
            {
                searchNode = GetNode(searchNode->m_listNext);
            }
            else
            {
                break;
            }
        }

        // 如果节点已经在正确位置，无需移动
        int currentNodeIdx = nodeToInsert->m_self;
        if (insertAfterIdx == INVALID_ID)
        {
            // 应该插入到头部
            if (currentNodeIdx == m_listHead)
            {
                // 已经在头部，无需移动
                currentIdx = nextIdx;
                continue;
            }
        }
        else
        {
            // 应该插入到insertAfterIdx之后
            Node* insertAfterNode = GetNode(insertAfterIdx);
            if (insertAfterNode != nullptr && insertAfterNode->m_listNext == currentNodeIdx)
            {
                // 已经在正确位置，无需移动
                currentIdx = nextIdx;
                continue;
            }
        }

        // 先从当前位置移除节点
        RemoveFromList(nodeToInsert);

        // 插入到正确位置
        if (insertAfterIdx == INVALID_ID)
        {
            // 插入到头部
            AddToListHead(nodeToInsert);
        }
        else
        {
            // 插入到指定节点之后
            Node* insertAfterNode = GetNode(insertAfterIdx);
            if (insertAfterNode != nullptr)
            {
                // 设置nodeToInsert的链接
                nodeToInsert->m_listPrev = insertAfterIdx;
                nodeToInsert->m_listNext = insertAfterNode->m_listNext;

                // 更新后继节点的前驱指针
                if (insertAfterNode->m_listNext != INVALID_ID)
                {
                    Node* nextNode = GetNode(insertAfterNode->m_listNext);
                    if (nextNode != nullptr)
                    {
                        nextNode->m_listPrev = currentNodeIdx;
                    }
                }
                else
                {
                    // 插入到尾部
                    m_listTail = currentNodeIdx;
                }

                // 更新前驱节点的后继指针
                insertAfterNode->m_listNext = currentNodeIdx;
            }
        }

        // 移动到下一个要处理的节点
        currentIdx = nextIdx;
    }
}

/**
 * @brief 链表排序的实现（使用自定义比较器）
 * @details 使用插入排序算法，直接在链表上进行原地排序
 * @note 时间复杂度：O(n²)，空间复杂度：O(1)
 * @note 排序过程中会保持链表的完整性和哈希表功能的正确性
 * @note 稳定排序：相等元素保持原有顺序
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::SortListInsert(StrictWeakOrdering comp)
{
    // 检查初始化状态
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    // 空链表或单元素链表无需排序
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_listHead == m_listTail)
    {
        return;
    }

    // 使用插入排序算法
    insertion_sort(comp);

    // 验证排序后链表的完整性
    CHECK_EXPR_RE_VOID(ValidateListIntegrity(), "List integrity validation failed after sorting, TRACE_STACK:%s", TRACE_STACK());
}

/**
 * @brief 链表高效排序的实现（使用自定义比较器）
 * @param comp 比较函数对象
 * @details 使用std::sort进行高效排序，时间复杂度O(n log n)，空间复杂度O(n)
 * @note 算法步骤：
 *       1. 收集所有节点索引到vector中（O(n)）
 *       2. 使用std::sort对索引数组排序，基于节点值比较（O(n log n)）
 *       3. 根据排序后的索引顺序重新连接链表指针（O(n)）
 *       4. 更新链表头尾指针，保持哈希表结构完整性
 * @note 时间复杂度：O(n log n)，空间复杂度：O(n)
 * @note 算法特点：
 *       - 利用std::sort的高度优化实现（内省排序：快排+堆排+插排）
 *       - 性能稳定可靠，对各种数据分布都有良好表现
 *       - 实现简单，不容易出错，维护成本低
 *       - 比传统链表快排避免了栈溢出风险
 * @note 适用场景：
 *       - 大中型数据集排序（推荐 > 50个元素）
 *       - 性能要求较高的场景
 *       - 数据分布未知或可能极端的情况
 *       - 需要稳定性能保证的生产环境
 * @note 与其他排序方法对比：
 *       - vs SortListInsert: 大数据集上快很多，但内存开销更大
 *       - vs SortListMerge: 性能相近，但此方法更简单可靠
 *       - vs SortListSelect: 所有方面都优于选择排序
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::SortListQuick(StrictWeakOrdering comp)
{
    // 检查初始化状态
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    // 空链表或单元素链表无需排序
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_listHead == m_listTail)
    {
        return;
    }

    // 验证当前大小与实际链表长度一致性
    CHECK_EXPR_RE_VOID(m_size > 0 && m_size <= MAX_SIZE, "Invalid size %d, valid range [1, %d], TRACE_STACK:%s", m_size, MAX_SIZE, TRACE_STACK());

    try
    {
        // 收集所有节点索引到vector中
        // 使用reserve预分配内存，避免动态扩容开销
        std::vector<int> nodeIndices;
        nodeIndices.reserve(m_size);

        // 遍历链表收集所有有效节点索引
        int current = m_listHead;
        size_t actualCount = 0;
        while (current != INVALID_ID && actualCount < m_size)
        {
            Node* currentNode = GetNode(current);
            if (!currentNode)
            {
                LOG_ERR(0, -1, "Invalid node found at index %d during collection, TRACE_STACK:%s", current, TRACE_STACK());
                break;
            }

            // 验证节点的有效性
            if (!currentNode->m_valid)
            {
                LOG_ERR(0, -1, "Invalid node state at index %d during collection, TRACE_STACK:%s", current, TRACE_STACK());
                break;
            }

            nodeIndices.push_back(current);
            current = currentNode->m_listNext;
            actualCount++;
        }

        // 验证收集到的节点数量与m_size一致
        if (nodeIndices.size() != m_size)
        {
            LOG_ERR(0, -1, "Node count mismatch: expected %d, collected %zu, TRACE_STACK:%s", m_size, nodeIndices.size(), TRACE_STACK());
            return;
        }

        // 使用std::sort进行高效排序
        // 比较器使用lambda表达式，捕获this和comp
        // 添加空指针检查，确保排序过程的安全性
        std::sort(nodeIndices.begin(), nodeIndices.end(), [this, comp](int a, int b) -> bool
        {
            Node* pA = GetNode(a);
            Node* pB = GetNode(b);

            // 双重安全检查：确保节点指针有效
            if (!pA || !pB)
            {
                // 如果节点无效，保持原有顺序
                return false;
            }

            // 验证节点状态
            if (!pA->m_valid || !pB->m_valid)
            {
                return false;
            }

            // 调用用户提供的比较器
            return comp(pA->m_value, pB->m_value);
        });

        // 根据排序后的索引重新连接链表
        reconnect_list(nodeIndices);

        // 更新头尾指针
        if (!nodeIndices.empty())
        {
            m_listHead = nodeIndices.front();
            m_listTail = nodeIndices.back();

            // 验证头尾节点的有效性
            Node* headNode = GetNode(m_listHead);
            Node* tailNode = GetNode(m_listTail);
            CHECK_EXPR_RE_VOID(headNode && headNode->m_valid, "Invalid head node after sorting, TRACE_STACK:%s", TRACE_STACK());
            CHECK_EXPR_RE_VOID(tailNode && tailNode->m_valid, "Invalid tail node after sorting, TRACE_STACK:%s", TRACE_STACK());
            CHECK_EXPR_RE_VOID(headNode->m_listPrev == INVALID_ID, "Head node prev pointer should be INVALID_ID, TRACE_STACK:%s", TRACE_STACK());
            CHECK_EXPR_RE_VOID(tailNode->m_listNext == INVALID_ID, "Tail node next pointer should be INVALID_ID, TRACE_STACK:%s", TRACE_STACK());
        }
        else
        {
            // 这种情况不应该发生，但作为安全措施
            m_listHead = INVALID_ID;
            m_listTail = INVALID_ID;
            LOG_ERR(0, -1, "Empty node indices after collection, resetting list pointers, TRACE_STACK:%s", TRACE_STACK());
        }
    }
    catch (const std::exception& e)
    {
        // 捕获标准异常
        LOG_ERR(0, -1, "Standard exception in SortListQuick: %s, TRACE_STACK:%s", e.what(), TRACE_STACK());
        return;
    }
    catch (...)
    {
        // 捕获所有其他异常
        LOG_ERR(0, -1, "Unknown exception in SortListQuick, TRACE_STACK:%s", TRACE_STACK());
        return;
    }

    // 验证排序后链表的完整性
    CHECK_EXPR_RE_VOID(ValidateListIntegrity(), "List integrity validation failed after SortListQuick, TRACE_STACK:%s", TRACE_STACK());
}

/**
 * @brief 链表排序方法3的实现（使用自定义比较器）
 * @param comp 比较函数对象
 * @details 使用简化的递归归并排序算法，时间复杂度O(n log n)，空间复杂度O(log n)
 * @note 算法步骤：
 *       1. 使用递归分治策略将链表分成两半
 *       2. 递归排序左右两个子链表
 *       3. 合并两个已排序的子链表
 *       4. 保持哈希表结构完整，只重新链接链表指针
 * @note 优势：实现简单可靠，性能稳定
 * @note 稳定排序：保持相等元素的相对顺序
 * @note 适用场景：中大型数据集排序，实现简单可靠
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::SortListMerge(StrictWeakOrdering comp)
{
    // 检查初始化状态
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    // 空链表或单元素链表无需排序
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_listHead == m_listTail)
    {
        return;
    }

    // 递归归并排序
    auto result = merge_sort_recursive(m_listHead, comp);

    // 更新链表头尾指针
    m_listHead = result.first;
    m_listTail = result.second;

    // 修复链表头尾的prev/next指针
    if (m_listHead != INVALID_ID)
    {
        Node* headNode = GetNode(m_listHead);
        if (headNode)
        {
            headNode->m_listPrev = INVALID_ID;
        }
    }
    if (m_listTail != INVALID_ID)
    {
        Node* tailNode = GetNode(m_listTail);
        if (tailNode)
        {
            tailNode->m_listNext = INVALID_ID;
        }
    }

    // 验证排序后链表的完整性
    CHECK_EXPR_RE_VOID(ValidateListIntegrity(), "List integrity validation failed after SortListMerge, TRACE_STACK:%s", TRACE_STACK());
}

/**
 * @brief 递归归并排序主函数
 * @param head 链表头节点索引
 * @param comp 比较函数对象
 * @return 排序后链表的头节点和尾节点索引
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
std::pair<int, int> NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::merge_sort_recursive(int head, StrictWeakOrdering comp)
{
    // 基本情况：空链表或单节点
    if (head == INVALID_ID)
    {
        return {INVALID_ID, INVALID_ID};
    }

    Node* headNode = GetNode(head);
    if (!headNode || headNode->m_listNext == INVALID_ID)
    {
        return {head, head};
    }

    // 分割链表为两半
    int secondHalf = split_list_half(head);

    // 递归排序两个子链表
    auto leftResult = merge_sort_recursive(head, comp);
    auto rightResult = merge_sort_recursive(secondHalf, comp);

    // 合并两个已排序的子链表
    return merge_two_lists(leftResult.first, rightResult.first, comp);
}

/**
 * @brief 分割链表为两半
 * @param head 链表头节点索引
 * @return 第二半链表的头节点索引
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::split_list_half(int head)
{
    if (head == INVALID_ID)
    {
        return INVALID_ID;
    }

    Node* headNode = GetNode(head);
    if (!headNode || headNode->m_listNext == INVALID_ID)
    {
        return INVALID_ID;
    }

    // 使用快慢指针找到中点
    int slow = head;
    int fast = head;
    int prev = INVALID_ID;

    while (fast != INVALID_ID)
    {
        Node* fastNode = GetNode(fast);
        if (!fastNode)
            break;

        fast = fastNode->m_listNext;
        if (fast != INVALID_ID)
        {
            Node* fastNextNode = GetNode(fast);
            if (!fastNextNode)
                break;
            fast = fastNextNode->m_listNext;
        }

        prev = slow;
        Node* slowNode = GetNode(slow);
        if (!slowNode)
            break;
        slow = slowNode->m_listNext;
    }

    // 在中点处断开链表
    if (prev != INVALID_ID)
    {
        Node* prevNode = GetNode(prev);
        if (prevNode)
        {
            prevNode->m_listNext = INVALID_ID;
        }
    }

    if (slow != INVALID_ID)
    {
        Node* slowNode = GetNode(slow);
        if (slowNode)
        {
            slowNode->m_listPrev = INVALID_ID;
        }
    }

    return slow;
}

/**
 * @brief 合并两个已排序的链表
 * @param left 左链表头节点索引
 * @param right 右链表头节点索引
 * @param comp 比较函数对象
 * @return 合并后链表的头节点和尾节点索引
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
std::pair<int, int> NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::merge_two_lists(int left, int right, StrictWeakOrdering comp)
{
    if (left == INVALID_ID && right == INVALID_ID)
    {
        return {INVALID_ID, INVALID_ID};
    }
    if (left == INVALID_ID)
    {
        // 找到右链表的尾节点
        int tail = right;
        while (tail != INVALID_ID)
        {
            Node* tailNode = GetNode(tail);
            if (!tailNode || tailNode->m_listNext == INVALID_ID)
                break;
            tail = tailNode->m_listNext;
        }
        return {right, tail};
    }
    if (right == INVALID_ID)
    {
        // 找到左链表的尾节点
        int tail = left;
        while (tail != INVALID_ID)
        {
            Node* tailNode = GetNode(tail);
            if (!tailNode || tailNode->m_listNext == INVALID_ID)
                break;
            tail = tailNode->m_listNext;
        }
        return {left, tail};
    }

    int resultHead = INVALID_ID;
    int resultTail = INVALID_ID;
    int leftCurrent = left;
    int rightCurrent = right;

    // 合并两个已排序的链表
    while (leftCurrent != INVALID_ID && rightCurrent != INVALID_ID)
    {
        Node* leftNode = GetNode(leftCurrent);
        Node* rightNode = GetNode(rightCurrent);

        if (!leftNode || !rightNode)
            break;

        int nextToAdd;
        if (comp(leftNode->m_value, rightNode->m_value))
        {
            nextToAdd = leftCurrent;
            leftCurrent = leftNode->m_listNext;
        }
        else
        {
            nextToAdd = rightCurrent;
            rightCurrent = rightNode->m_listNext;
        }

        // 添加选中的节点到结果链表
        Node* addNode = GetNode(nextToAdd);
        if (addNode)
        {
            addNode->m_listNext = INVALID_ID;
            addNode->m_listPrev = resultTail;

            if (resultHead == INVALID_ID)
            {
                resultHead = nextToAdd;
                resultTail = nextToAdd;
                addNode->m_listPrev = INVALID_ID;
            }
            else
            {
                Node* tailNode = GetNode(resultTail);
                if (tailNode)
                {
                    tailNode->m_listNext = nextToAdd;
                }
                resultTail = nextToAdd;
            }
        }
    }

    // 添加剩余的左链表节点
    while (leftCurrent != INVALID_ID)
    {
        Node* leftNode = GetNode(leftCurrent);
        if (!leftNode)
            break;

        int next = leftNode->m_listNext;
        leftNode->m_listNext = INVALID_ID;
        leftNode->m_listPrev = resultTail;

        if (resultHead == INVALID_ID)
        {
            resultHead = leftCurrent;
            resultTail = leftCurrent;
            leftNode->m_listPrev = INVALID_ID;
        }
        else
        {
            Node* tailNode = GetNode(resultTail);
            if (tailNode)
            {
                tailNode->m_listNext = leftCurrent;
            }
            resultTail = leftCurrent;
        }

        leftCurrent = next;
    }

    // 添加剩余的右链表节点
    while (rightCurrent != INVALID_ID)
    {
        Node* rightNode = GetNode(rightCurrent);
        if (!rightNode)
            break;

        int next = rightNode->m_listNext;
        rightNode->m_listNext = INVALID_ID;
        rightNode->m_listPrev = resultTail;

        if (resultHead == INVALID_ID)
        {
            resultHead = rightCurrent;
            resultTail = rightCurrent;
            rightNode->m_listPrev = INVALID_ID;
        }
        else
        {
            Node* tailNode = GetNode(resultTail);
            if (tailNode)
            {
                tailNode->m_listNext = rightCurrent;
            }
            resultTail = rightCurrent;
        }

        rightCurrent = next;
    }

    return {resultHead, resultTail};
}

/**
 * @brief 重新连接链表节点的实现
 * @param nodeIndices 排序后的节点索引数组
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::reconnect_list(const std::vector<int>& nodeIndices)
{
    if (nodeIndices.empty())
    {
        return;
    }

    // 重新连接所有节点
    for (size_t i = 0; i < nodeIndices.size(); i++)
    {
        Node* node = GetNode(nodeIndices[i]);
        if (!node)
            continue;

        // 设置前向指针
        if (i == 0)
        {
            node->m_listPrev = INVALID_ID;
        }
        else
        {
            node->m_listPrev = nodeIndices[i - 1];
        }

        // 设置后向指针
        if (i == nodeIndices.size() - 1)
        {
            node->m_listNext = INVALID_ID;
        }
        else
        {
            node->m_listNext = nodeIndices[i + 1];
        }
    }
}

/**
 * @brief 链表排序方法4的实现（使用自定义比较器）
 * @param comp 比较函数对象
 * @details 使用选择排序算法，时间复杂度O(n²)，空间复杂度O(1)
 * @note 算法步骤：
 *       1. 从链表头开始，找到剩余链表中的最小元素
 *       2. 如果最小元素不是当前位置，交换值
 *       3. 移动到下一个位置，重复步骤1-2
 *       4. 直到遍历完整个链表
 * @note 优势：实现简单，稳定性能，原地排序
 * @note 劣势：时间复杂度O(n²)，不稳定排序
 * @note 适用场景：简单可靠的排序需求
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::SortListSelect(StrictWeakOrdering comp)
{
    // 检查初始化状态
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    // 空链表或单元素链表无需排序
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_listHead == m_listTail)
    {
        return;
    }

    // 调用选择排序实现
    selection_sort(comp);

    // 验证排序后链表的完整性
    CHECK_EXPR_RE_VOID(ValidateListIntegrity(), "List integrity validation failed after SortListSelect, TRACE_STACK:%s", TRACE_STACK());
}

/**
 * @brief 选择排序的实现
 * @param comp 比较函数
 * @details 在链表上进行选择排序，只改变链表链接顺序，不改变节点值，保持哈希表完整性
 * @note 时间复杂度：O(n²)，空间复杂度：O(n)
 * @note 算法保持哈希表完整性，只操作链表指针
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::selection_sort(StrictWeakOrdering comp)
{
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID)
    {
        return;
    }

    // 构建有序的链表，不改变节点值，只重新链接
    std::vector<int> sortedNodeIndices;

    // 收集所有节点索引
    int current = m_listHead;
    while (current != INVALID_ID)
    {
        Node* currentNode = GetNode(current);
        if (!currentNode)
            break;

        sortedNodeIndices.push_back(current);
        current = currentNode->m_listNext;
    }

    // 使用选择排序对节点索引进行排序（基于节点值的比较）
    for (size_t i = 0; i < sortedNodeIndices.size(); ++i)
    {
        size_t minIndex = i;
        Node* minNode = GetNode(sortedNodeIndices[i]);

        for (size_t j = i + 1; j < sortedNodeIndices.size(); ++j)
        {
            Node* compareNode = GetNode(sortedNodeIndices[j]);
            if (compareNode && minNode && comp(compareNode->m_value, minNode->m_value))
            {
                minIndex = j;
                minNode = compareNode;
            }
        }

        // 交换索引（不是节点值）
        if (minIndex != i)
        {
            std::swap(sortedNodeIndices[i], sortedNodeIndices[minIndex]);
        }
    }

    // 重新链接链表指针
    for (size_t i = 0; i < sortedNodeIndices.size(); ++i)
    {
        Node* node = GetNode(sortedNodeIndices[i]);
        if (!node)
            continue;

        // 设置前驱指针
        if (i == 0)
        {
            node->m_listPrev = INVALID_ID;
            m_listHead = sortedNodeIndices[i];
        }
        else
        {
            node->m_listPrev = sortedNodeIndices[i - 1];
        }

        // 设置后继指针
        if (i == sortedNodeIndices.size() - 1)
        {
            node->m_listNext = INVALID_ID;
            m_listTail = sortedNodeIndices[i];
        }
        else
        {
            node->m_listNext = sortedNodeIndices[i + 1];
        }
    }
}

// ==================== 排序插入接口实现 ====================

/**
 * @brief 排序插入唯一元素的实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
std::pair<typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator, bool> NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_list_sorted_unique(const value_type& obj, Compare comp)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, (std::pair<iterator, bool>(iterator(nullptr, this), false)), "not init, TRACE_STACK:%s", TRACE_STACK());

    // 使用现有的insert_unique_noresize进行常规插入
    // 这会处理重复键检查、容量检查、哈希表插入等所有逻辑
    std::pair<iterator, bool> result = insert_unique_noresize(obj);

    // 如果插入失败（重复键或容量满），直接返回
    if (!result.second)
    {
        return result;
    }

    try
    {
        MoveToNodeSorted(result.first, comp);
    }
    catch (...)
    {
        // 如果移动过程中出现异常，保持元素在当前位置
        // 这比删除元素更安全，因为元素至少已经成功插入到哈希表中
        LOG_ERR(0, -1, "Failed to move node to sorted position, keeping at current position, TRACE_STACK:%s", TRACE_STACK());
    }

    return result;
}

/**
 * @brief 排序插入允许重复元素的实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::iterator NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_list_sorted_equal(const value_type& obj, Compare comp)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, iterator(nullptr, this), "not init, TRACE_STACK:%s", TRACE_STACK());

    // 使用现有的insert_equal_noresize进行常规插入
    // 这会处理容量检查、哈希表插入等所有逻辑
    iterator result = insert_equal_noresize(obj);

    // 如果插入失败（容量满），直接返回
    if (result == end())
    {
        return result;
    }

    try
    {
        // 使用优化的排序版本进行高效插入位置查找
        // 如果链表已经有序，使用二分搜索O(log n)；否则使用线性搜索O(n)
        MoveToNodeSorted(result, comp);
    }
    catch (...)
    {
        // 如果移动过程中出现异常，保持元素在当前位置
        // 这比删除元素更安全，因为元素至少已经成功插入到哈希表中
        LOG_ERR(0, -1, "Failed to move node to sorted position, keeping at current position, TRACE_STACK:%s", TRACE_STACK());
    }

    return result;
}

// ==================== 有序链表优化版本实现 ====================

/**
 * @brief 有序链表中的优化移动到前面实现（使用二分搜索）
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToNodeSorted(const_iterator iter, Compare comp)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode != nullptr, "Iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode->m_valid, "Iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    // 检查链表不为空
    if (m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_size <= 1)
    {
        return; // 空链表或单元素，无需移动
    }

    Node* pSelfNode = const_cast<Node*>(iter.m_curNode);

    // 使用二分搜索找到插入位置
    Node* pFindNode = AdaptiveSearchInsertPosition(pSelfNode, comp);
    if (pFindNode == nullptr)
    {
        if (pSelfNode->m_self != m_listTail)
        {
            RemoveFromList(pSelfNode);
            AddToListTail(pSelfNode);
        }
    }
    else
    {
        if (pFindNode->m_listPrev != pSelfNode->m_self)
        {
            MoveToListNodeFront(pSelfNode, pFindNode);
        }
    }
}

/**
 * @brief 有序链表中的优化移动到前面实现（链表迭代器版本）
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::MoveToNodeSorted(const_list_iterator iter, Compare comp)
{
    CHECK_EXPR_RE_VOID(m_init == EN_NF_SHM_STL_INIT_OK, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode != nullptr, "List iterator is null, TRACE_STACK:%s", TRACE_STACK());
    CHECK_EXPR_RE_VOID(iter.m_curNode->m_valid, "List iterator points to invalid node, TRACE_STACK:%s", TRACE_STACK());

    // 转换为普通迭代器并调用对应的实现
    iterator normalIter(const_cast<Node*>(iter.m_curNode), const_cast<NFShmHashTableWithList*>(iter.m_hashTable));
    MoveToNodeSorted(normalIter, comp);
}

// ==================== 二分搜索辅助函数实现 ====================

/**
 * @brief 在有序链表中使用二分搜索找到插入位置
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::BinarySearchInsertPosition(Node* pSelfNode, Compare comp)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, nullptr, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    if (pSelfNode == nullptr || m_listHead == INVALID_ID)
    {
        return nullptr;
    }

    // 对于小数据集，使用线性搜索更高效
    if (m_size <= 16)
    {
        return LineSearchInsertPosition(pSelfNode, comp);
    }

    // 直接获取节点数组，避免重复的GetNode调用
    Node* nodes = GetBuckets();
    if (nodes == nullptr)
    {
        return nullptr;
    }

    // 使用栈分配的数组来收集索引，避免动态内存分配
    int nodeIndices[MAX_SIZE];
    int indexCount = 0;

    // 收集有序节点索引（排除自身）
    int current = m_listHead;
    int iterCount = 0;
    while (current != INVALID_ID && indexCount < MAX_SIZE && iterCount < m_size)
    {
        if (current != pSelfNode->m_self)
        {
            nodeIndices[indexCount++] = current;
        }
        current = nodes[current].m_listNext;
        iterCount++;
    }

    if (indexCount == 0)
    {
        return nullptr;
    }

    // 二分查找插入位置
    int left = 0;
    int right = indexCount;

    while (left < right)
    {
        int mid = left + (right - left) / 2;

        if (comp(pSelfNode->m_value, nodes[nodeIndices[mid]].m_value))
        {
            right = mid;
        }
        else
        {
            left = mid + 1;
        }
    }

    // 返回插入位置的节点
    if (left < indexCount)
    {
        return &nodes[nodeIndices[left]];
    }

    return nullptr; // 插入到尾部
}

template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::LineSearchInsertPosition(Node* pSelfNode, Compare comp)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, nullptr, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    if (pSelfNode == nullptr || m_listHead == INVALID_ID)
    {
        return nullptr;
    }

    // 直接获取节点数组指针，避免重复的GetNode调用
    Node* nodes = GetBuckets();
    if (nodes == nullptr)
    {
        return nullptr;
    }

    // 优化策略：减少重复取值和函数调用开销
    const auto& target_value = pSelfNode->m_value;
    const int target_self = pSelfNode->m_self;

    int current = m_listHead;
    int count = 0;

    // 优化的线性搜索：内联关键操作，减少开销
    while (current != INVALID_ID && count < m_size)
    {
        if (current != target_self)
        {
            // 内联比较操作，避免重复解引用
            if (comp(target_value, nodes[current].m_value))
            {
                return &nodes[current];
            }
        }

        current = nodes[current].m_listNext;
        count++;
    }

    return nullptr; // 插入到尾部
}

/**
 * @brief 将有序链表转换为索引数组
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::CollectSortedNodeIndices(std::vector<int>& nodeIndices, Node* pSelfNode)
{
    nodeIndices.clear();
    nodeIndices.reserve(m_size);

    int current = m_listHead;
    while (current != INVALID_ID)
    {
        if (pSelfNode)
        {
            if (current != pSelfNode->m_self)
            {
                nodeIndices.push_back(current);
            }
        }
        else
        {
            nodeIndices.push_back(current);
        }
        Node* currentNode = GetNode(current);
        if (!currentNode)
            break;
        current = currentNode->m_listNext;
    }
}

/**
 * @brief 使用std::lower_bound和std::upper_bound查找插入位置
 * @note 利用标准库的高效实现，代码更简洁且性能更优
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::FindSortedInsertPosition(const std::vector<int>& nodeIndices, Node* pTargetNode, Compare comp)
{
    // 输入验证
    if (nodeIndices.empty() || pTargetNode == nullptr || !pTargetNode->m_valid || pTargetNode->m_self < 0 || pTargetNode->m_self >= MAX_SIZE)
    {
        return nullptr; // 空数组，插入到位置0
    }

    // 创建正确的比较器适配器
    // std::lower_bound和std::upper_bound需要一个比较器：comp(element, value)
    // 其中element是容器中的元素，value是要查找的值
    auto indexComparator = [this, comp](int a, int b) -> bool
    {
        Node* pNodeA = GetNode(a);
        Node* pNodeB = GetNode(b);
        if (pNodeA && pNodeB)
        {
            return comp(pNodeA->m_value, pNodeB->m_value);
        }
        return false;
    };

    try
    {
        // 插入到相等元素后面，使用upper_bound
        // upper_bound返回第一个大于(>)target的位置
        auto it = std::upper_bound(nodeIndices.begin(), nodeIndices.end(), pTargetNode->m_self, indexComparator);

        if (it != nodeIndices.end())
        {
            // 返回第一个大于目标值的节点，新元素将插入到这个节点之前
            return GetNode(*it);
        }

        return nullptr;
    }
    catch (const std::exception& e)
    {
        // 标准库算法出现异常，回退到线性搜索
        LOG_ERR(0, -1, "std::lower_bound/upper_bound failed: %s, falling back to linear search, TRACE_STACK:%s", e.what(), TRACE_STACK());
        return nullptr;
    }
    catch (...)
    {
        // 未知异常，回退到线性搜索
        LOG_ERR(0, -1, "Unknown exception in binary search, falling back to linear search, TRACE_STACK:%s", TRACE_STACK());
        return nullptr;
    }
}

/**
 * @brief 高性能归并排序实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::SortListMergeFast(StrictWeakOrdering comp)
{
    // 快速初始化检查，减少分支
    if (m_init != EN_NF_SHM_STL_INIT_OK || m_listHead == INVALID_ID || m_listTail == INVALID_ID || m_listHead == m_listTail)
    {
        return;
    }

    // 缓存节点数组指针，避免重复GetNode调用
    Node* nodes = GetBuckets();

    // 根据数据规模选择最优算法
    if (m_size <= 32)
    {
        // 小数据集：插入排序
        insertion_sort_fast(nodes, comp);
    }
    else if (m_size <= 1000)
    {
        // 中数据集：优化归并排序
        auto result = merge_sort_recursive_fast(m_listHead, nodes, comp);
        m_listHead = result.first;
        m_listTail = result.second;
    }
    else
    {
        // 大数据集：迭代归并排序
        merge_sort_iterative_fast(nodes, comp);
    }

    // 修复头尾指针（直接数组访问）
    if (m_listHead != INVALID_ID)
    {
        nodes[m_listHead].m_listPrev = INVALID_ID;
    }
    if (m_listTail != INVALID_ID)
    {
        nodes[m_listTail].m_listNext = INVALID_ID;
    }
}

/**
 * @brief 快速插入排序实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insertion_sort_fast(Node* nodes, StrictWeakOrdering comp)
{
    if (m_listHead == INVALID_ID)
        return;

    int current = nodes[m_listHead].m_listNext;

    while (current != INVALID_ID)
    {
        int next = nodes[current].m_listNext;
        int insertPos = m_listHead;

        // 找到插入位置
        while (insertPos != current && !comp(nodes[current].m_value, nodes[insertPos].m_value))
        {
            insertPos = nodes[insertPos].m_listNext;
        }

        // 如果需要移动
        if (insertPos != current)
        {
            // 从当前位置移除
            remove_from_list_fast(current, nodes);
            // 插入到新位置
            insert_before_fast(current, insertPos, nodes);
        }

        current = next;
    }
}

/**
 * @brief 快速递归归并排序实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
std::pair<int, int> NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::merge_sort_recursive_fast(int head, Node* nodes, StrictWeakOrdering comp)
{
    // 基本情况
    if (head == INVALID_ID)
    {
        return {INVALID_ID, INVALID_ID};
    }

    if (nodes[head].m_listNext == INVALID_ID)
    {
        return {head, head};
    }

    // 快速分割链表
    int secondHalf = split_list_fast(head, nodes);

    // 递归排序
    auto leftResult = merge_sort_recursive_fast(head, nodes, comp);
    auto rightResult = merge_sort_recursive_fast(secondHalf, nodes, comp);

    // 快速合并
    return merge_two_lists_fast(leftResult.first, rightResult.first, nodes, comp);
}

/**
 * @brief 快速链表分割实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::split_list_fast(int head, Node* nodes)
{
    if (head == INVALID_ID || nodes[head].m_listNext == INVALID_ID)
    {
        return INVALID_ID;
    }

    // 快慢指针（直接数组访问）
    int slow = head;
    int fast = head;
    int prev = INVALID_ID;

    while (fast != INVALID_ID)
    {
        fast = nodes[fast].m_listNext;
        if (fast != INVALID_ID)
        {
            fast = nodes[fast].m_listNext;
        }

        prev = slow;
        slow = nodes[slow].m_listNext;
    }

    // 断开链表
    if (prev != INVALID_ID)
    {
        nodes[prev].m_listNext = INVALID_ID;
    }
    if (slow != INVALID_ID)
    {
        nodes[slow].m_listPrev = INVALID_ID;
    }

    return slow;
}

/**
 * @brief 快速合并两个已排序链表实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
std::pair<int, int> NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::merge_two_lists_fast(int left, int right, Node* nodes, StrictWeakOrdering comp)
{
    if (left == INVALID_ID && right == INVALID_ID)
        return {INVALID_ID, INVALID_ID};

    if (left == INVALID_ID)
    {
        int tail = find_tail_fast(right, nodes);
        return {right, tail};
    }

    if (right == INVALID_ID)
    {
        int tail = find_tail_fast(left, nodes);
        return {left, tail};
    }

    int resultHead = INVALID_ID;
    int resultTail = INVALID_ID;
    int leftCurrent = left;
    int rightCurrent = right;

    // 主合并循环（优化版）
    while (leftCurrent != INVALID_ID && rightCurrent != INVALID_ID)
    {
        int nextToAdd;
        if (comp(nodes[leftCurrent].m_value, nodes[rightCurrent].m_value))
        {
            nextToAdd = leftCurrent;
            leftCurrent = nodes[leftCurrent].m_listNext;
        }
        else
        {
            nextToAdd = rightCurrent;
            rightCurrent = nodes[rightCurrent].m_listNext;
        }

        // 快速链接节点
        append_to_result_fast(nextToAdd, resultHead, resultTail, nodes);
    }

    // 添加剩余节点
    int remaining = (leftCurrent != INVALID_ID) ? leftCurrent : rightCurrent;
    if (remaining != INVALID_ID)
    {
        if (resultHead == INVALID_ID)
        {
            resultHead = remaining;
            resultTail = find_tail_fast(remaining, nodes);
        }
        else
        {
            nodes[resultTail].m_listNext = remaining;
            nodes[remaining].m_listPrev = resultTail;
            resultTail = find_tail_fast(remaining, nodes);
        }
    }

    return {resultHead, resultTail};
}

/**
 * @brief 迭代归并排序实现（大数据集优化）
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class StrictWeakOrdering>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::merge_sort_iterative_fast(Node* nodes, StrictWeakOrdering comp)
{
    // 使用标准库排序 + 链表重建（对大数据集最优）
    std::vector<int> nodeIndices;
    nodeIndices.reserve(m_size);

    // 收集所有节点索引
    int current = m_listHead;
    while (current != INVALID_ID)
    {
        nodeIndices.push_back(current);
        current = nodes[current].m_listNext;
    }

    // 使用高性能标准库排序
    std::sort(nodeIndices.begin(), nodeIndices.end(), [&](int a, int b)
    {
        return comp(nodes[a].m_value, nodes[b].m_value);
    });

    // 重建链表
    rebuild_list_fast(nodeIndices, nodes);
}

/**
 * @brief 快速重建链表实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::rebuild_list_fast(const std::vector<int>& sortedIndices, Node* nodes)
{
    if (sortedIndices.empty())
    {
        m_listHead = m_listTail = INVALID_ID;
        return;
    }

    size_t size = sortedIndices.size();
    m_listHead = sortedIndices[0];
    m_listTail = sortedIndices[size - 1];

    // 设置第一个节点
    nodes[m_listHead].m_listPrev = INVALID_ID;
    nodes[m_listHead].m_listNext = (size > 1) ? sortedIndices[1] : INVALID_ID;

    // 设置中间节点
    for (size_t i = 1; i < size - 1; ++i)
    {
        int idx = sortedIndices[i];
        nodes[idx].m_listPrev = sortedIndices[i - 1];
        nodes[idx].m_listNext = sortedIndices[i + 1];
    }

    // 设置最后一个节点
    if (size > 1)
    {
        nodes[m_listTail].m_listPrev = sortedIndices[size - 2];
        nodes[m_listTail].m_listNext = INVALID_ID;
    }
}

/**
 * @brief 快速找到链表尾部实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::find_tail_fast(int head, Node* nodes)
{
    if (head == INVALID_ID)
        return INVALID_ID;

    int current = head;
    while (nodes[current].m_listNext != INVALID_ID)
    {
        current = nodes[current].m_listNext;
    }
    return current;
}

/**
 * @brief 将节点添加到结果链表实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::append_to_result_fast(int nodeIdx, int& resultHead, int& resultTail, Node* nodes)
{
    nodes[nodeIdx].m_listNext = INVALID_ID;
    nodes[nodeIdx].m_listPrev = resultTail;

    if (resultHead == INVALID_ID)
    {
        resultHead = nodeIdx;
        resultTail = nodeIdx;
        nodes[nodeIdx].m_listPrev = INVALID_ID;
    }
    else
    {
        nodes[resultTail].m_listNext = nodeIdx;
        resultTail = nodeIdx;
    }
}

/**
 * @brief 从链表中快速移除节点实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::remove_from_list_fast(int nodeIdx, Node* nodes)
{
    int prev = nodes[nodeIdx].m_listPrev;
    int next = nodes[nodeIdx].m_listNext;

    if (prev != INVALID_ID)
    {
        nodes[prev].m_listNext = next;
    }
    else
    {
        m_listHead = next;
    }

    if (next != INVALID_ID)
    {
        nodes[next].m_listPrev = prev;
    }
    else
    {
        m_listTail = prev;
    }
}

/**
 * @brief 在指定位置前快速插入节点实现
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
void NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::insert_before_fast(int nodeIdx, int beforeIdx, Node* nodes)
{
    if (beforeIdx == INVALID_ID)
    {
        // 插入到末尾
        nodes[nodeIdx].m_listNext = INVALID_ID;
        nodes[nodeIdx].m_listPrev = m_listTail;

        if (m_listTail != INVALID_ID)
        {
            nodes[m_listTail].m_listNext = nodeIdx;
        }
        m_listTail = nodeIdx;

        if (m_listHead == INVALID_ID)
        {
            m_listHead = nodeIdx;
        }
    }
    else
    {
        // 插入到beforeIdx前面
        int prev = nodes[beforeIdx].m_listPrev;

        nodes[nodeIdx].m_listNext = beforeIdx;
        nodes[nodeIdx].m_listPrev = prev;

        if (prev != INVALID_ID)
        {
            nodes[prev].m_listNext = nodeIdx;
        }
        else
        {
            m_listHead = nodeIdx;
        }

        nodes[beforeIdx].m_listPrev = nodeIdx;
    }
}

// ==================== 快速查找优化接口实现 ====================

/**
 * @brief 快速查找插入位置（使用SortListMergeFast技术优化）
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::FastSearchInsertPosition(Node* pSelfNode, Compare comp)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, nullptr, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    if (pSelfNode == nullptr || m_listHead == INVALID_ID)
    {
        return nullptr;
    }

    // 对于中小数据集，线性搜索实际上更高效
    if (m_size <= 200)
    {
        return LineSearchInsertPosition(pSelfNode, comp);
    }

    // 直接获取节点数组指针，避免重复的GetNode调用
    Node* nodes = GetBuckets();
    if (nodes == nullptr)
    {
        return nullptr;
    }

    // 使用改进的快速搜索算法
    int targetIndex = fast_binary_search_on_list_optimized(nodes, pSelfNode, comp);

    if (targetIndex == INVALID_ID)
    {
        return nullptr; // 插入到尾部
    }

    return &nodes[targetIndex];
}

/**
 * @brief 优化的快速搜索算法（改进版本）
 * @note 针对链表结构优化的线性搜索，使用预取和批量比较减少开销
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::fast_binary_search_on_list_optimized(Node* nodes, Node* pTargetNode, Compare comp)
{
    if (nodes == nullptr || pTargetNode == nullptr || m_listHead == INVALID_ID)
    {
        return INVALID_ID;
    }

    // 优化策略：减少函数调用开销，内联关键操作
    const auto& target_value = pTargetNode->m_value;
    const int target_self = pTargetNode->m_self;

    int current = m_listHead;
    int count = 0;

    // 批量处理：每次处理多个节点减少循环开销
    const int BATCH_SIZE = 4;

    while (current != INVALID_ID && count < m_size)
    {
        // 批量检查最多BATCH_SIZE个连续节点
        for (int batch = 0; batch < BATCH_SIZE && current != INVALID_ID && count < m_size; ++batch)
        {
            if (current != target_self)
            {
                // 内联比较操作，减少函数调用开销
                if (comp(target_value, nodes[current].m_value))
                {
                    return current;
                }
            }

            current = nodes[current].m_listNext;
            count++;
        }
    }

    return INVALID_ID; // 插入到尾部
}

/**
 * @brief 直接在链表上进行二分查找（无需额外内存分配）
 * @note 保留原始实现作为备用
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
int NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::fast_binary_search_on_list(Node* nodes, Node* pTargetNode, Compare comp)
{
    if (nodes == nullptr || pTargetNode == nullptr || m_listHead == INVALID_ID)
    {
        return INVALID_ID;
    }

    // 使用类似SortListMergeFast中split_list_fast的快慢指针技术
    // 但这里用于二分查找而非分割

    int left = m_listHead;
    int right = INVALID_ID;
    int count = 0;

    // 首先计算链表长度并找到尾节点
    int current = left;
    while (current != INVALID_ID && current != pTargetNode->m_self)
    {
        if (nodes[current].m_listNext == INVALID_ID || nodes[current].m_listNext == pTargetNode->m_self)
        {
            right = current;
            break;
        }
        current = nodes[current].m_listNext;
        count++;

        // 防止无限循环
        if (count > m_size)
        {
            return INVALID_ID;
        }
    }

    if (right == INVALID_ID)
    {
        return INVALID_ID;
    }

    // 执行二分查找
    while (left != INVALID_ID && left != right)
    {
        // 使用快慢指针找到中点，借鉴split_list_fast的技术
        int slow = left;
        int fast = left;
        int prev = INVALID_ID;

        // 移动到中点
        while (fast != INVALID_ID && fast != right && nodes[fast].m_listNext != INVALID_ID && nodes[fast].m_listNext != right)
        {
            prev = slow;
            slow = nodes[slow].m_listNext;
            fast = nodes[fast].m_listNext;
            if (fast != INVALID_ID && fast != right)
            {
                fast = nodes[fast].m_listNext;
            }
        }

        if (slow == INVALID_ID || slow == pTargetNode->m_self)
        {
            break;
        }

        // 比较中点元素与目标元素
        if (comp(pTargetNode->m_value, nodes[slow].m_value))
        {
            // 目标应插入到左半部分
            right = prev != INVALID_ID ? prev : left;
        }
        else if (comp(nodes[slow].m_value, pTargetNode->m_value))
        {
            // 目标应插入到右半部分
            left = nodes[slow].m_listNext;
        }
        else
        {
            // 找到相等元素，插入到其后
            return nodes[slow].m_listNext != INVALID_ID ? nodes[slow].m_listNext : INVALID_ID;
        }

        // 防止无限循环
        if (left == slow || (prev != INVALID_ID && left == prev))
        {
            break;
        }
    }

    // 找到合适的插入位置
    if (left != INVALID_ID && left != pTargetNode->m_self)
    {
        if (comp(pTargetNode->m_value, nodes[left].m_value))
        {
            return left;
        }
        else
        {
            return nodes[left].m_listNext != INVALID_ID ? nodes[left].m_listNext : INVALID_ID;
        }
    }

    return INVALID_ID;
}

/**
 * @brief 自适应查找策略：根据数据规模选择最优算法
 * @note 优化的策略选择，基于实际性能测试结果调整阈值
 */
template <class Val, class Key, int MAX_SIZE, class HashFcn, class ExtractKey, class EqualKey>
template <class Compare>
typename NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::Node* NFShmHashTableWithList<Val, Key, MAX_SIZE, HashFcn, ExtractKey, EqualKey>::AdaptiveSearchInsertPosition(Node* pSelfNode, Compare comp)
{
    CHECK_EXPR(m_init == EN_NF_SHM_STL_INIT_OK, nullptr, "HashTable not initialized, TRACE_STACK:%s", TRACE_STACK());

    if (pSelfNode == nullptr)
    {
        return nullptr;
    }

    // 自适应策略：基于实际测试结果优化的阈值
    // 根据测试发现：BinarySearch有2x开销，FastSearch与LineSearch相近
    if (m_size <= 300)
    {
        // 小中数据集：线性搜索表现最佳，开销最低
        return LineSearchInsertPosition(pSelfNode, comp);
    }
    else if (m_size <= 1000)
    {
        // 较大数据集：优化的快速搜索可能有微小优势
        return FastSearchInsertPosition(pSelfNode, comp);
    }
    else
    {
        // 超大数据集：线性搜索仍然是最佳选择
        // 因为链表的顺序访问特性，复杂算法的优势不明显
        return LineSearchInsertPosition(pSelfNode, comp);
    }
}
